Nils-Johan Gynther
e491a6c67f
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
169 lines
7.8 KiB
Markdown
169 lines
7.8 KiB
Markdown
# 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
|
|
```bash
|
|
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`
|
|
```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 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:
|
|
```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.
|
|
```
|
|
|
|
---
|
|
|
|
## 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. |