Skip to main content

Guia de documentació de Line Dance Platform

Aquest document explica com està organitzada la documentació del projecte Line Dance Platform (LDP), quins blocs hi ha i en quin ordre és recomanable llegir-los segons el teu rol (nou dev, arquitecte, PM, etc.).

La documentació viu dins aquesta web (docs-web) i està pensada per ser viva i mantinguda al dia, igual que el codi.

🔎 Estructura global de la documentació​

Les seccions principals són:

1. Overview​

Documents d’alta nivell per entendre què és el projecte i amb quines tecnologies es construeix.

  • intro
    Resum del projecte i de la documentació.

  • overview/vision
    Visió del projecte, objectius, públic objectiu i roadmap d’alt nivell.

  • overview/tech-stack
    Stack tecnològic (backend, frontend, mòbil, BD, integracions, DevOps).

2. Architecture​

Documents d’arquitectura funcional i tècnica.

  • architecture/architecture-overview
    Visió general de l’arquitectura (components principals, fronteres, fluxos d’API).

  • architecture/identity-model
    Model d’identitat i relació entre usuaris, rols, coreògrafs, etc.

  • architecture/db-redesign-plan
    Pla de redisseny de la base de dades, entitats clau i estratègia d’evolució.

  • architecture/import-system
    Disseny del sistema d’importació (staging, fonts externes, enriquiment de dades).

  • architecture/security
    Conceptes de seguretat (autenticació, rols, permisos, JWT, futures ampliacions).

  • architecture/events-wizard
    Disseny del flux de creació/edició d’events i els seus passos.

  • architecture/ownership-workflow
    Workflow de “propietat” / “claim” de fitxes (coreògrafs, etc.).

  • architecture/diagrams
    Referència a diagrames (PlantUML, Mermaid, etc.) i on trobar-los al repo.

3. Roadmap​

Documents d’evolució del producte i estat de les fases.

  • roadmap/roadmap-global
    Taula de fases (1, 2, 3, 4A, 4B, …), estat (COMPLETAT/EN CURS/PENDENT) i enllaços.

  • roadmap/backlog
    Backlog més detallat: tasques, idees en curs, prioritats.

  • roadmap/roadmap-technical-details
    Detalls tècnics per fase (decisions, dependències, notes).

  • roadmap/avatar-feature
    Detall d’aquesta feature concreta (si aplica).

  • roadmap/ideas
    Llista d’idees de roadmap que encara no tenen fase assignada.

4. Dev​

Guies pràctiques per desenvolupar.

  • dev/backend-setup
    Configuració i arquitectura tècnica del backend (requisits, Maven, Flyway, BD, Docker).

  • dev/dev-guide
    Guia pas a pas per arrencar el projecte en local, provar l’API i fer troubleshooting.

En el futur es poden afegir:

  • dev/frontend-setup
  • dev/mobile-setup (o equivalents) quan es documentin aquests blocs.

5. Repos & Envs​

On es documenten repositoris i entorns.

  • repos-envs/repos-overview
    Llista i rol dels repos (backend, frontend, docs-web, app mòbil…).

  • repos-envs/environments
    Entorns (local, dev, stage, prod), URLs i diferències principals.

6. Ops & History​

Operacions i historial.

  • ops/changelog
    Canvis operatius (infra, pipelines, canvis en entorns).

  • history/changelog
    Històric global de canvis del projecte (feature grans, milestones).

7. AI & Idees​

Rols d’IA i espai d’idees.

  • ai/ai-roles
    Definició de rols d’IA (assistents per backend, frontend, arquitectura, ops, data, etc.).

  • ideas/idea-dump
    “Contenidor” d’idees que encara no s’han estructurat al roadmap.

8. Meta​

  • meta/docs-guide (aquest document) Com està organitzada la documentació i com mantenir-la.

9. Claude Code (.claude/)​

Capa complementària a docs-web per a l'entorn de desenvolupament amb Claude Code:

  • .claude/commands/ — Slash commands: procediments estàndard invocables amb /project:nom

    • new-feature — Planificar una nova funcionalitat
    • diagnostic — Diagnosticar un problema
    • code-review — Revisar canvis de codi
    • add-entity — Scaffold complet d'una nova entitat
    • migration — Crear migració Flyway segura

  • .claude/knowledge/ — Coneixement operatiu acumulat

    • patterns.md — Patrons recurrents, trucs, lliçons apreses (creix amb cada sessió)
    • current-focus.md — Estat viu del treball en curs

Regla: docs-web/ conté la documentació formal del projecte. .claude/ conté eines i estat operatiu per al flux de treball amb IA. No es duplica contingut entre les dues capes.

🧭 Ordre de lectura recomanat per rol​

Nous desenvolupadors (onboarding)​

  1. overview/vision
    Entendre què és LDP i per què existeix.
  2. overview/tech-stack
    Veure les tecnologies i eines que s’utilitzen.
  3. dev/dev-guide
    Arrencar el projecte en local i provar una crida a l’API.
  4. architecture/architecture-overview
    Entendre l’arquitectura MVP (components i fluxos principals).
  5. dev/backend-setup (si faràs backend)
    Profunditzar en la part tècnica de backend.

Product Managers / Stakeholders​

  1. overview/vision
    Visió, objectius, públic i roadmap d’alt nivell.
  2. roadmap/roadmap-global
    Estat de les fases i properes passes.
  3. architecture/architecture-overview
    Entendre entitats i relacions (contracte funcional).
  4. architecture/diagrams (si vols una visió més visual)
    Diagrames d’arquitectura i mapes mentals.

Arquitectes / Tech Leads​

  1. overview/tech-stack
    Decisions de stack tecnològic.
  2. architecture/architecture-overview
    Arquitectura MVP i evolució prevista.
  3. architecture/db-redesign-plan
    Model de dades i estratègia de refactor.
  4. architecture/import-system
    Disseny del sistema d’import i enriquiment.
  5. architecture/security
    Línies mestres de seguretat i autenticació.
  6. roadmap/roadmap-technical-details
    Detall tècnic per fase.

Backend developers​

  1. dev/dev-guide
    Arrencar el projecte i provar l’API.
  2. dev/backend-setup
    Configuració profunda del backend (Maven, Spring Boot, Flyway, BD).
  3. architecture/architecture-overview
    Relació entre serveis, entitats i endpoints.
  4. architecture/db-redesign-plan
    Disseny de la BD i planificació de canvis.
  5. architecture/security
    JWT, rols, permisos i patrons de seguretat.

Frontend / Mobile developers​

(Més endavant això es podrà refinar amb docs específiques.)

  1. overview/vision
    Entendre el producte i els casos d’ús.
  2. overview/tech-stack
    Veure el stack web/mòbil i les integracions.
  3. architecture/architecture-overview
    Entendre com el frontend i l’app parlen amb l’API.
  4. roadmap/roadmap-global
    Veure quines funcionalitats són prioritàries.

🧱 Principis per mantenir la documentació​

Algunes normes bàsiques per evitar que la doc es descontroli:

  1. 1 tema = 1 document

    • Si un .md comença a ser massa llarg i barreja molts conceptes, considera dividir-lo.

  2. Sincronitzar codi i doc

    • Quan introdueixis canvis importants (API, model de dades, fluxos), revisa si cal:
      • Actualitzar architecture/*
      • Actualitzar dev/*
      • Actualitzar roadmap/* o history/changelog

  3. Actualitzar el roadmap i l’històric

    • Quan es tanca una fase o un milestone:
      • Marca l’estat a roadmap/roadmap-global.
      • Afegeix una entrada resumida a history/changelog.

  4. No crear documents orfes

    • Sempre que creïs un .md nou:
      • Afegeix-lo al sidebars.ts.
      • Afegeix (si cal) un enllaç des de meta/docs-guide.md o des d’un document “pare” clar.

  5. Tractar la doc com codi

    • Canvis a la doc s’han de fer amb commit i, si pot ser, en la mateixa branch/PR que els canvis de codi relacionats.
    • Llegeix els .md en el navegador (npm run start) per comprovar que els enllaços funcionen.

🧳 Migració des de l’antiga carpeta docs/​

Abans existia una carpeta docs/ amb fitxers com:

  • 00-vision.md
  • 01-tech-stack.md
  • 03-arquitectura.md
  • 04-backend-setup.md
  • 05-guia-desenvolupament.md
  • 06-db-redesign-plan.md
  • 07-import-system.md
  • 08-security.md
  • 11-events-wizard.md
  • 02-ia-rols.md
  • CHANGELOG.md
  • etc.

La idea és:

  • NO afegir-hi contingut nou a aquests fitxers antics.
  • Migrar-los progressivament a la nova estructura:
    • 00-vision.md → overview/vision
    • 01-tech-stack.md → overview/tech-stack
    • 03-arquitectura.md → architecture/architecture-overview (+ altres subdocs)
    • 04-backend-setup.md → dev/backend-setup
    • 05-guia-desenvolupament.md → dev/dev-guide
    • 06-db-redesign-plan.md → architecture/db-redesign-plan
    • 07-import-system.md → architecture/import-system
    • 08-security.md → architecture/security
    • 11-events-wizard.md → architecture/events-wizard
    • 02-ia-rols.md → ai/ai-roles
    • CHANGELOG.md → history/changelog o ops/changelog segons el cas

Quan el contingut d’un fitxer antic ja estigui totalment migrat a Docusaurus, es pot:

  • marcar com “deprecated” a l’antic repo, o
  • mantenir-lo només com a referència històrica.

📌 Resum​

  • Aquesta web de docs (docs-web) és el punt central de la documentació del projecte.
  • meta/docs-guide.md (aquest fitxer) és la porta d’entrada per entendre on va cada cosa.
  • Quan dubtis on posar un contingut nou:
    • Mira les seccions (Overview, Architecture, Roadmap, Dev, Repos & Envs, Ops & History, AI & Idees, Meta).
    • Tria la categoria més propera.
    • Si no encaixa enlloc, posa’l provisionalment a ideas/idea-dump i ja es categoritzarà més endavant.

La documentació ha de ser una eina que ajudi a pensar, decidir i desenvolupar, no un arxiu mort: és normal que canvïi i s’afini a mesura que el projecte creix.