nilsjohan/recipe-app

Fork 0

Files

T

Nils-Johan Gynther e491a6c67f

Test Suite / backend-pr-quick (push) Has been skipped

Details

Test Suite / quick-import-pr-quick (push) Has been skipped

Details

Test Suite / backend-full (push) Successful in 1m32s

Details

Test Suite / flutter-quality (push) Failing after 1m12s

Details

docs: add new documentation files for project planning and development

Added two new documentation files:
- .kilo/plans/1779256422838-glowing-knight.md: Contains development plan for the "Glowing Knight" feature
- plan-dokumentation.md: Provides overview of project planning structure and documentation standards

2026-05-20 21:28:10 +02:00

17 KiB

Raw Blame History

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

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.
**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.
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:

# 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

Flutter App:
- State management: Riverpod
- UI: Material Design + anpassade widgets
- Integreringar: Kamera (kvittoscan), PDF-rendering
Backend API:
- Ramverk: NestJS
- Databas: Prisma + MariaDB
- Autentisering: JWT
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

Konfigurera miljö:

cp .env.example .env
# Redigera .env (se CONFIG.md för detaljer)

Starta tjänster:
```
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

Uppdatera prisma/schema.prisma.

Skapa migration:

npx prisma migrate dev --name add_feature_x

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.

Seedning

Initial data: Laddas från db/seeds/seed_all.sql.
Kör seed:
```
./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

Kör migrationer:
```
./deploy.sh --backend --migrate
```
Starta tjänster:
```
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.

17 KiB Raw Blame History

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

Bakgrund

Mål med ny struktur

Föreslagen struktur

Detaljerad filstruktur och innehåll

1. docs/01-overview/

Komponenter

Migrationer

Standardflöde

Underhållsskript

Seedning

Vanliga flaggor

API-endpoints

Underhåll

17 KiB

Raw Blame History

1. `docs/01-overview/`