# Plan: Förbättrad dokumentationsstruktur för Recipe-app

## Bakgrund
Projektet har idag **20+ .md-filer** spridda över olika mappar, inklusive:
- **Aktiva filer** i rotmappen (t.ex. `TEKNISK_BESKRIVNING.md`, `NEXT_STEPS.md`).
- **Arkiverade filer** i `_archive/docs/` (t.ex. session-specifika anteckningar, gamla refaktoringsplaner).
- **Fragmenterade guider** (t.ex. `flyerimporter.md`, `filanalys.md`).
- **GitHub-specifika filer** (t.ex. `.github/copilot-instructions.md`).

**Problem**:
- **Svårt att hitta information**: 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`).
- **Icke-optimerat för språkmodeller**: Saknar tydlig hierarki och kontextuella länkar.
- **Duplicering**: Samma koncept (t.ex. "kategoriträd") dokumenteras på flera ställen.

---

## Mål med ny struktur
1. **Användarvänligt för utvecklare**:
   - Logisk gruppering av innehåll (t.ex. "Backend", "Flutter", "Deploy").
   - Tydliga **steg-för-steg-guider** för vanliga arbetsflöden.
   - **Sökbart** med tydliga rubriker och nyckelord.

2. **Optimerat för språkmodeller (LLMs):
   - **Kontextuell sammanhang**: Varje fil innehåller tillräcklig bakgrund för att förstå dess syfte.
   - **Länkat innehåll**: Korsreferenser mellan filer för att ge fullständig bild.
   - **Strukturera data**: Använd tabeller, listor och diagram för att göra informationen maskinläsbar.

3. **Underhållbart**:
   - **Versionerat**: Tydlig separation mellan aktiv dokumentation och arkiv.
   - **Modulärt**: Uppdateringar i en modul (t.ex. "Databas") påverkar inte andra.
   - **Automatiseringsvänligt**: Filer som `CONTRIBUTING.md` och `README.md` kan genereras delvis från andra källor.

---

## Föreslagen struktur
```
/
├── docs/                  # **Huvudkatalog för ALL aktiv dokumentation**
│   ├── 01-overview/       # Övergripande projektbeskrivning
│   │   ├── README.md       # Huvudsaklig README (ersätter rot-README.md)
│   │   ├── ARCHITECTURE.md  # Systemarkitektur (flytta från TEKNISK_BESKRIVNING.md)
│   │   └── GLOSSARY.md     # Termer och definitioner (t.ex. "kategoriträd", "flyer session")
│   │
│   ├── 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 (flytta från TEKNISK_BESKRIVNING.md)
│   │   ├── API.md            # Backend-API:er, Swagger-länkar, exempelanrop
│   │   ├── FLUTTER.md       # Flutter-specifik dokumentation (flytta från _archive/docs/flutter/)
│   │   └── MICROSERVICES.md  # Importer-AI, Todo-microservice, etc.
│   │
│   ├── 04-deploy/         # Driftsättning och underhåll
│   │   ├── DEPLOY.md        # Steg-för-steg deploy (ersätter delar av TEKNISK_BESKRIVNING.md)
│   │   ├── MAINTENANCE.md   # Underhållsskript, backup, monitorering
│   │   └── SCALING.md       # Prestanda, skalning, lasttest
│   │
│   ├── 05-features/       # Djupdyk i funktioner
│   │   ├── RECIPE_IMPORT.md # Kvittosimport (ersätter flyerimporter.md)
│   │   ├── CATEGORY_TREE.md # Kategorihantering och L3-integration
│   │   ├── SHOPPING_LIST.md # Inköpslistor och flyer-integration
│   │   └── ...             # Övriga funktioner (t.ex. måltidsplanering)
│   │
│   └── 06-archive/        # **Arkiverade dokument** (flytta hit från _archive/)
│       ├── sessions/       # Gamla sessionsanteckningar
│       ├── legacy/         # Föråldrade planer (t.ex. RECIPE_IMPORT_REFACTOR_PLAN.md)
│       └── ...
│
├── .github/               # GitHub-specifika filer
│   ├── COPILOT_INSTRUCTIONS.md # Flytta hit från .github/copilot-instructions.md
│   └── ...
│
└── ...                   # Övriga projektfiler (backend/, flutter/, etc.)
```

---

## Detaljerad filstruktur och innehåll

### 1. `docs/01-overview/`
| Fil               | Syfte                                                                 | Källor (befintliga filer)                          |
|-------------------|-----------------------------------------------------------------------|---------------------------------------------------|
| `README.md`       | **Huvudsaklig ingress**: Projektbeskrivning, mål, snabbstart, länkar. | `README.md`, delar av `TEKNISK_BESKRIVNING.md`   |
| `ARCHITECTURE.md` | **Systemarkitektur**: Komponentdiagram, databasrelationer, flöden.   | `TEKNISK_BESKRIVNING.md` (avsnitt om arkitektur)  |
| `GLOSSARY.md`    | **Ordförklaringar**: Definitioner av projekt-specifika termer.         | Ny fil                                              |

**Exempelinnehåll för `ARCHITECTURE.md`**:
```markdown
# 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: Riverpod
   - UI: Material Design + anpassade widgets
   - Integreringar: Kamera (kvittoscan), PDF-rendering

2. **Backend API**: 
   - Ramverk: NestJS
   - Databas: Prisma + MariaDB
   - Autentisering: JWT

3. **Microservices**:
   - Importer: Node.js + Puppeteer (för kvittosimport)
   - AI: Python + Mistral (för kategorisering)
```

---

### 2. `docs/02-setup/`
| Fil               | Syfte                                                                 | Källor                                      |
|-------------------|-----------------------------------------------------------------------|----------------------------------------------|
| `INSTALL.md`      | **Miljösetup**: Krav, beroenden, första körning.                     | Delar av `README.md` och `TEKNISK_BESKRIVNING.md` |
| `CONFIG.md`       | **Konfiguration**: `.env`-variabler, Docker-compose, nätverk.        | `TEKNISK_BESKRIVNING.md` (avsnitt om miljö) |
| `TROUBLESHOOTING.md` | **Felsökning**: Vanliga fel, lösningar, debug-tips.                   | Ny fil                                      |

**Exempelinnehåll för `INSTALL.md`**:
```markdown
# Installation

## Krav
| Komponent       | Version       | Notering                          |
|-----------------|---------------|-----------------------------------|
| Node.js         | 24.15.0       | LTS-version rekommenderas         |
| Docker          | 24.x          | Krävs för databas och microservices|
| Flutter         | 3.41.9        | Kanal: stable                     |
| MariaDB         | 11.x          | Inkluderas via Docker-compose     |

## Steg-för-steg
1. **Klona repo**:
   ```bash
   git clone https://github.com/recipe-app/recipe-app.git
   cd recipe-app
   ```

2. **Konfigurera miljö**:
   ```bash
   cp .env.example .env
   # Redigera .env (se CONFIG.md för detaljer)
   ```

3. **Starta tjänster**:
   ```bash
   docker compose up -d
   ```
```

---

### 3. `docs/03-development/`
| Fil               | Syfte                                                                 | Källor                                      |
|-------------------|-----------------------------------------------------------------------|----------------------------------------------|
| `CONTRIBUTING.md` | **Bidragsregler**: Kodstandard, PR-process, testkrav.                 | Ny fil (inspirerad av GitHub-standard)      |
| `WORKFLOWS.md`    | **Arbetsflöden**: Git-strategi, CI/CD, release-process.               | `TEKNISK_BESKRIVNING.md` (avsnitt om Git)   |
| `DATABASE.md`     | **Databas**: Schema, migrationer, seedning, underhållsskript.         | `TEKNISK_BESKRIVNING.md` + nya avsnitt      |
| `API.md`          | **Backend-API**: Endpoints, autentisering, exempelanrop.               | Ny fil                                      |
| `FLUTTER.md`      | **Flutter-utveckling**: Widget-träd, state management, teman.         | `_archive/docs/flutter/`                    |
| `MICROSERVICES.md`| **Microservices**: Importer, AI, kommunikation med backend.           | Ny fil                                      |

**Exempelinnehåll för `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:
   ```bash
   npx prisma migrate dev --name add_feature_x
   ```
3. Testa lokalt:
   ```bash
   npx prisma migrate reset
   npx prisma db seed
   ```

### Underhållsskript
- **Rensa databas** (behåll kategorier):
  ```bash
  ./deploy.sh --clean-database
  ```
  > Obs! Uppdatera `prisma/maintenance/clean-database.sql` när nya tabeller läggs till.

## Seedning
- **Initial data**: Laddas från `db/seeds/seed_all.sql`.
- **Kör seed**:
  ```bash
  ./deploy.sh --seed
  ```
```

---

### 4. `docs/04-deploy/`
| Fil               | Syfte                                                                 | Källor                                      |
|-------------------|-----------------------------------------------------------------------|----------------------------------------------|
| `DEPLOY.md`       | **Deploy-guider**: Steg-för-steg för staging/produktion.               | `TEKNISK_BESKRIVNING.md` (avsnitt om deploy) |
| `MAINTENANCE.md`  | **Underhåll**: Backup, monitorering, logghantering.                   | Ny fil                                      |
| `SCALING.md`      | **Skalning**: Prestandaoptimering, lasttest, caching.                 | Ny fil                                      |

**Exempelinnehåll för `DEPLOY.md`**:
```markdown
# Driftsättning

## Miljöer
| Miljö       | Domän               | Syfte                          |
|-------------|---------------------|--------------------------------|
| Lokal       | localhost:8080      | Utveckling                     |
| Staging     | staging.app.com     | Test перед prod                |
| Produktion  | app.recipe.com      | Live-trafik                    |

## Steg-för-steg
1. **Bygg och pusha images**:
   ```bash
   docker compose build
   docker compose push
   ```

2. **Kör migrationer**:
   ```bash
   ./deploy.sh --backend --migrate
   ```

3. **Starta tjänster**:
   ```bash
   docker compose up -d
   ```

## Vanliga flaggor
| Flagga            | Beskrivning                                  |
|-------------------|----------------------------------------------|
| `--migrate`       | Kör Prisma-migrationer.                      |
| `--clean-database`| Rensar data (behåller kategorier).          |
| `--seed`          | Laddar initial data.                         |
```

---

### 5. `docs/05-features/`
| Fil               | Syfte                                                                 | Källor                                      |
|-------------------|-----------------------------------------------------------------------|----------------------------------------------|
| `RECIPE_IMPORT.md`| **Kvittosimport**: Flyer-parsing, AI-kategorisering, lagring.         | `flyerimporter.md`                          |
| `CATEGORY_TREE.md`| **Kategoriträd**: L3-integration, hierarki, synkronisering.          | Delar av `TEKNISK_BESKRIVNING.md`           |
| `SHOPPING_LIST.md`| **Inköpslistor**: Flyer-integration, kvantitetsberäkning, delning.   | Ny fil                                      |

**Exempelinnehåll för `RECIPE_IMPORT.md`**:
```markdown
# Kvittosimport

## Flöde
```mermaid
flowchart TD
  A[Ladda upp PDF] --> B[Extrahera text]
  B --> C[AI-kategorisering]
  C --> D[Spara som FlyerSession]
  D --> E[Mappa till inköpslista]
```

## API-endpoints
| Endpoint                          | Metod | Beskrivning                          |
|-----------------------------------|-------|--------------------------------------|
| `/api/flyer-sessions`            | POST  | Ladda upp och parsa PDF.             |
| `/api/flyer-sessions/:id/items`   | PATCH | Uppdatera produktnamn/kategori.      |
| `/api/shopping-list/from-flyer`   | POST  | Konvertera flyer till inköpslista.   |

## Underhåll
- **Uppdatera AI-modell**: Se `MICROSERVICES.md`.
- **Lägg till nya butiker**: Uppdatera `src/flyer-import/parsers/`.
```

---

### 6. `docs/06-archive/`
- **Syfte**: Flytta alla föråldrade filer hit, organiserade efter typ:
  ```
  docs/06-archive/
  ├── sessions/          # Gamla sessionscheckpoints
  │   ├── SESSION_2026-05-09_RECEIPT_IMPORT.md
  │   └── ...
  ├── legacy/            # Föråldrade planer
  │   ├── RECIPE_IMPORT_REFACTOR_PLAN.md
  │   └── ...
  └── flutter_legacy/   # Gamla Flutter-dokument
      ├── teknisk_beskrivning_flutter.md
      └── ...
  ```

---

## Migrationsplan

### Steg 1: Rensa och organisera befintliga filer
| Åtgärd                          | Källfil(er)                                  | Målfil                                  |
|---------------------------------|---------------------------------------------|-----------------------------------------|
| Flytta och uppdatera           | `TEKNISK_BESKRIVNING.md`                    | `docs/01-overview/ARCHITECTURE.md`       |
|                                 | `TEKNISK_BESKRIVNING.md` (deploy-avsnitt)   | `docs/04-deploy/DEPLOY.md`              |
|                                 | `TEKNISK_BESKRIVNING.md` (databas-avsnitt)  | `docs/03-development/DATABASE.md`        |
| Flytta och slå samman           | `flyerimporter.md`                         | `docs/05-features/RECIPE_IMPORT.md`      |
|                                 | `_archive/docs/flutter/*`                   | `docs/03-development/FLUTTER.md`         |
| Arkivera                        | `_archive/docs/SESSION_*.md`                | `docs/06-archive/sessions/`              |
|                                 | `MVP_CHECKLISTA.md`                         | `docs/06-archive/legacy/`                |
| Uppdatera och flytta            | `README.md`                                 | `docs/01-overview/README.md`            |
|                                 | `.github/copilot-instructions.md`            | `.github/COPILOT_INSTRUCTIONS.md`        |

### Steg 2: 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/Swagger-länkar).          |
| `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.                              |

### Steg 3: Lägg till kontext för språkmodeller
- **Länka filer**: Korsreferenser mellan relaterade ämnen (t.ex. länka från `DATABASE.md` till `DEPLOY.md` för migrationssteg).
- **Metadatarubriker**: Lägg till `## Syfte` och `## Målgrupp` i varje fil.
- **Diagram**: Använd Mermaid för att visualisera flöden och relationer.
- **Exempel**: Inkludera kopierbara kodblock för vanliga operationer.

---

## Fördelar med den nya strukturen

### För utvecklare
✅ **Lätt att hitta**: Logisk gruppering (t.ex. all Flutter-dokumentation på ett ställe).
✅ **Uppdaterad**: Arkiverade filer separerade från aktiv dokumentation.
✅ **Steg-för-steg**: Guider med tydliga exempel (t.ex. `INSTALL.md`).

### För språkmodeller (LLMs)
🤖 **Kontextuell förståelse**:
- Varje fil har ett tydligt syfte och målgrupp.
- Korsreferenser ger fullständig bild (t.ex. länka från `ARCHITECTURE.md` till `DATABASE.md`).
- Diagram och tabeller gör informationen maskinläsbar.

📚 **Sökbarhet**:
- Hierarkisk struktur (`01-overview/`, `02-setup/`, etc.) underlättar navigering.
- Nyckelord i rubriker (t.ex. "Flutter State Management" i `FLUTTER.md`).

🔗 **Länkat innehåll**:
- Relaterade ämnen länkas explicit (t.ex. "Se [DATABASE.md](../03-development/DATABASE.md) för schema").

---

## Nästa steg
1. **Godkänn planen**: Bekräfta att den föreslagna strukturen uppfyller kraven.
2. **Prioritera filer**: Vilka filer ska migreras först? (t.ex. `TEKNISK_BESKRIVNING.md` → flera nya filer).
3. **Implementera**: Skapa den nya strukturen och flytta innehåll stegvis.