recipe-app/plan-dokumentation.md

Plan för förbättrad dokumentationsstruktur

Bakgrund

Projektet har idag över 20 .md-filer spridda över olika mappar, vilket gör det svårt att hitta information och förstå projektets helhet. Den nya strukturen syftar till att:

• Göra dokumentationen användarvänlig för både utvecklare och språkmodeller.
• Optimerad för underhåll med tydlig separation mellan aktiv och arkiverad dokumentation.
• Skapa kontextuell sammanhang genom länkade filer och tydliga hierarkier.

---

Nuvarande problem

• Fragmentering: Relaterat innehåll är splittrat (t.ex. Flutter-dokumentation i _archive/docs/flutter/ vs. backend-dokumentation i rotmappen).
• Föråldrat innehåll: Arkiverade filer blandas med aktiva (t.ex. SESSION_CHECKPOINT_2026-05-12.md).
• Duplicering: Samma koncept dokumenteras på flera ställen (t.ex. kategoriträd).
• Icke-optimerat för språkmodeller: Saknar tydlig hierarki och kontextuella länkar.

---

Föreslagen struktur

/
├── docs/                  # Huvudkatalog för ALL aktiv dokumentation
│   ├── 01-overview/       # Övergripande projektbeskrivning
│   │   ├── README.md       # Huvudsaklig ingress (ersätter rot-README.md)
│   │   ├── ARCHITECTURE.md  # Systemarkitektur
│   │   └── GLOSSARY.md     # Termer och definitioner
│   │
│   ├── 02-setup/          # Installation och konfiguration
│   │   ├── INSTALL.md      # Miljökrav, beroenden, första uppstart
│   │   ├── CONFIG.md        # Konfigurationsfiler (.env, Docker, etc.)
│   │   └── TROUBLESHOOTING.md # Vanliga problem och lösningar
│   │
│   ├── 03-development/   # Utvecklingsguider
│   │   ├── CONTRIBUTING.md # Bidragsregler, kodstandard, PR-process
│   │   ├── WORKFLOWS.md     # Git-flöden, branch-strategi, CI/CD
│   │   ├── DATABASE.md      # Schema, migrationer, seedning
│   │   ├── API.md            # Backend-API:er, Swagger-länkar
│   │   ├── FLUTTER.md       # Flutter-specifik dokumentation
│   │   └── MICROSERVICES.md  # Importer, AI, etc.
│   │
│   ├── 04-deploy/         # Driftsättning och underhåll
│   │   ├── DEPLOY.md        # Steg-för-steg deploy
│   │   ├── MAINTENANCE.md   # Underhållsskript, backup, monitorering
│   │   └── SCALING.md       # Prestanda, skalning
│   │
│   ├── 05-features/       # Djupdyk i funktioner
│   │   ├── RECIPE_IMPORT.md # Kvittosimport och flyer-parsing
│   │   ├── CATEGORY_TREE.md # Kategorihantering och L3-integration
│   │   ├── SHOPPING_LIST.md # Inköpslistor och flyer-integration
│   │   └── ...             # Övriga funktioner
│   │
│   └── 06-archive/        # Arkiverade dokument
│       ├── sessions/       # Gamla sessionsanteckningar
│       ├── legacy/         # Föråldrade planer
│       └── flutter_legacy/ # Gamla Flutter-dokument
│
├── .github/               # GitHub-specifika filer
│   ├── COPILOT_INSTRUCTIONS.md
│   └── ...
│
└── ...                   # Övriga projektfiler (backend/, flutter/, etc.)

---

Migrationsplan

Steg 1: Skapa den nya strukturen

mkdir -p docs/{01-overview,02-setup,03-development,04-deploy,05-features,06-archive/sessions,06-archive/legacy,06-archive/flutter_legacy}

Steg 2: Flytta och uppdatera filer

Källfil(er)	Målfil	Åtgärd
TEKNISK_BESKRIVNING.md	docs/01-overview/ARCHITECTURE.md	Extrahera arkitekturavsnitt.
TEKNISK_BESKRIVNING.md (deploy)	docs/04-deploy/DEPLOY.md	Extrahera deploy-avsnitt.
TEKNISK_BESKRIVNING.md (databas)	docs/03-development/DATABASE.md	Extrahera databasavsnitt + lägg till underhållsskript.
flyerimporter.md	docs/05-features/RECIPE_IMPORT.md	Uppdatera med nya flöden och API-endpoints.
_archive/docs/flutter/*	docs/03-development/FLUTTER.md	Slå samman och uppdatera Flutter-dokumentation.
README.md	docs/01-overview/README.md	Uppdatera med länkar till nya dokument.
.github/copilot-instructions.md	.github/COPILOT_INSTRUCTIONS.md	Flytta och uppdatera.
_archive/docs/SESSION_*.md	docs/06-archive/sessions/	Arkivera gamla sessionsanteckningar.
MVP_CHECKLISTA.md	docs/06-archive/legacy/	Arkivera föråldrade planer.

Steg 3: Skapa nya filer

Fil	Syfte
docs/03-development/CONTRIBUTING.md	Standardiserade bidragsregler (branches, PR, code review).
docs/03-development/API.md	Dokumentation av backend-API:er (OpenAPI-länkar, exempel).
docs/03-development/MICROSERVICES.md	Beskrivning av microservices (Importer, AI).
docs/05-features/CATEGORY_TREE.md	Djupdyk i kategorihantering och L3-integration.
docs/04-deploy/MAINTENANCE.md	Backup, monitorering, logghantering.

---

Exempel på innehåll

docs/01-overview/ARCHITECTURE.md

# Systemarkitektur

```mermaid
graph TD
  A[Flutter App] -->|HTTP/REST| B[Backend API]
  B -->|Prisma Client| C[MariaDB]
  B -->|gRPC| D[Importer Microservice]
  D -->|HTTP| E[Externa API:er]
  C -->|Seed| F[Initial Data]

Komponenter

1. Flutter App: State management med Riverpod, UI med Material Design.
2. Backend API: NestJS + Prisma, autentisering via JWT.
3. Microservices: Importer (Node.js + Puppeteer), AI (Python + Mistral).

---

### `docs/03-development/DATABASE.md`
```markdown
# Databas

## Schema
```mermaid
erDiagram
  User ||--o{ Recipe : creates
  User ||--o{ InventoryItem : owns
  Category ||--o{ Product : "L3"
  FlyerSession ||--o{ FlyerItem : contains

Migrationer

Standardflöde

1. Uppdatera prisma/schema.prisma.
2. Skapa migration:

   npx prisma migrate dev --name add_feature_x
   

3. Testa lokalt:

   npx prisma migrate reset
   npx prisma db seed
   

Underhållsskript

• Rensa databas (behåll kategorier):

  ./deploy.sh --clean-database
  

  Obs! Uppdatera prisma/maintenance/clean-database.sql när nya tabeller läggs till.

---

## Fördelar
- **Lätt att hitta**: Logisk gruppering (t.ex. all Flutter-dokumentation på ett ställe).
- **Uppdaterad**: Arkiverade filer separerade från aktiv dokumentation.
- **Optimerad för språkmodeller**: Tydliga rubriker, länkar, och maskinläsbara format.
- **Underhållbar**: Modulär struktur gör det enkelt att uppdatera enskilda delar.

---

## Nästa steg
1. **Godkänn planen**: Bekräfta att strukturen uppfyller era behov.
2. **Implementera**: Skapa den nya strukturen och flytta filer stegvis.
3. **Uppdatera länkar**: Se till att alla referenser pekar på de nya platserna.