chore(docs): consolidate legacy documentation into new structure
- Removed outdated documentation files (MVP_CHECKLISTA.md, NEXT_STEPS.md, README.md, TEKNISK_BESKRIVNING.md, filanalys.md, flyerimporter.md, kilo.json, plan-dokumentation.md) - Added new centralized documentation structure under docs/ directory - Added .kilo/ directory for Kilo AI agent configuration and plans BREAKING CHANGE: Legacy documentation files removed and replaced with new centralized structure
This commit is contained in:
Nils-Johan Gynther
@@ -0,0 +1,169 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user