Skip to main content

Visió general de l'arquitectura

Aquest document descriu la visió d’arquitectura de Line Dance Platform (LDP) per al MVP i la Fase 3 (autenticació). És el punt de partida per entendre com es connecten frontend, backend, base de dades i integracions.

Visió ràpida (C4, nivell contenidors)​

  • Frontend web (React)

    • Cerca de balls i cançons.
    • Visualització de fitxes.
    • Pantalles d’autenticació i gestió bàsica.

  • Backend API (Spring Boot)

    • REST API per a totes les apps (web, mòbil, altres futurs clients).
    • Autenticació i autorització amb JWT (access + refresh tokens).
    • Lògica de negoci i validacions.

  • Base de dades (PostgreSQL)

    • Emmagatzema metadades de:
      • balls, cançons, coreògrafs,
      • enllaços,
      • usuaris,
      • (futur) events, venues, locations, classes.
    • Índexos per cerca (FTS/pg_trgm, etc.).

  • Integracions externes

    • Enllaços cap a:
      • YouTube (vídeos d’ensenyament, demos, exhibicions),
      • Spotify / Apple Music / altres (cançons),
      • portals de stepsheets.
    • No es redistribueix contingut extern; només es guarden metadades i URLs.

  • Docs-web (Docusaurus)

    • Documentació viva de:
      • visió,
      • arquitectura,
      • roadmap,
      • guies de desenvolupament,
      • changelog.

Components principals​

Frontend web​

  • Tech stack: React + TypeScript.
  • Rol:
    • interfície per a usuaris avançats (professors, admins),
    • gestió de metadades (balls, cançons, enllaços, coreògrafs, etc.),
    • consulta més rica i filtres avançats.
  • Consum:
    • API REST del backend (/api/...).
    • Flux d’autenticació amb JWT.

App mòbil (Android)​

  • Tech stack: Kotlin + Jetpack Compose.
  • Rol:
    • accés ràpid a la informació des del mòbil (ballarins/professors),
    • cercar ball ↔ cançó,
    • consultar fitxes i, en el futur, agenda d’events.
  • Consum:
    • Mateixa API REST que el frontend web.

Backend API​

  • Tech stack: Spring Boot (Java).
  • Rol:
    • exposar API REST segura,
    • implementar la lògica de negoci,
    • validar dades i coordinar persistència.
  • Conceptes clau:
    • DTOs per separar model intern de format d’API.
    • Serveis de domini (DanceService, SongService, etc.).
    • Repositoris JPA per a cada entitat principal.

Base de dades​

  • Tech stack: PostgreSQL.
  • Rol:
    • guardar entitats de domini i relacions.
  • Utilitza:
    • Flyway per controlar canvis d’esquema,
    • índexos específics per cerques i ordres freqüents.

Integracions​

  • No hi ha dependència forta d’APIs externes al MVP:
    • es treballa amb URLs públiques.
  • Futur (Fase 4+):
    • possibles integracions més profundes (YouTube Data API, etc.), sempre respectant TOS i drets.

Domini (MVP + Fase 3)​

Entitats principals (MVP)​

  • Dance

    • Representa un ball concret (p. ex. “Wagon Wheel Rock”).
    • Camps típics:
      • name, level, walls, counts, tags, year, choreographer, etc.
    • Relacions:
      • té un o més links (vídeos, música, stepsheets).

  • Song

    • Representa una cançó.
    • Camps típics:
      • title, artist, album, bpm?, year?, isrc?.
    • Relacions:
      • es pot associar a múltiples dances.

  • Link

    • Enllaç cap a:
      • vídeo (YouTube),
      • cançó (Spotify, Apple Music),
      • stepsheet,
      • web de referència.
    • Camps:
      • kind (enum: YOUTUBE_VIDEO, SPOTIFY_TRACK, STEPSHEET, etc.),
      • url,
      • metadades opcionals (títol, descripció curta).

  • Level

    • Nivell del ball:
      • BEGINNER, INTERMEDIATE, ADVANCED, EXPERT, etc.

Aquestes entitats formen el nucli del MVP: cercar i relacionar balls i cançons.

Entitats futures (Fase 4+)​

Definides o planificades al pla de redisseny de BD:

  • Choreographer

    • Persona o grup que crea coreografies.
    • Es relaciona amb dances.

  • Venue

    • Sala o local on es fan ballades, classes, etc.
    • Es relaciona amb location.

  • Location

    • Ciutat/país i coordenades, possible estructura jeràrquica.
    • Pot tenir molts venues.

  • Event

    • Ballades, socials, festivals, workshops.
    • Relació event → venue i event → occurrences (dates/horaris).

  • Class

    • Classes regulars o puntuals.
    • Relació amb venue, instructor i dance.

Els detalls d’aquestes entitats i la seva evolució es documenten a:
👉 architecture/db-redesign-plan.md

Autenticació i seguretat (Fase 3)​

La Fase 3 introdueix:

  • Usuari (User)

    • id, email (únic, case-insensitive),
    • passwordHash (BCrypt),
    • role (USER, TEACHER, ADMIN),
    • tokenVersion,
    • createdAt, updatedAt.

  • Rols

    • USER: lectura de dades públiques.
    • TEACHER: pot crear i editar determinades entitats (balls, cançons, enllaços) segons permisos.
    • ADMIN: control complet del sistema.

  • JWT

    • access token (curta durada: ~15 min),
    • refresh token (llarga durada: ~7 dies, cookie httpOnly).
    • Claims mínims:
      • sub (email),
      • uid (user id),
      • role,
      • tv (token version).

  • Fluxos principals

    • Login (/auth/login),
    • Refresh (/auth/refresh),
    • Logout (/auth/logout, /auth/logoutAll),
    • Endpoint d’usuari actual (/auth/me).

Detall complet:
👉 architecture/security.md
👉 history/changelog.md (Fase 3 - JWT)

Diagrames relacionats​

Els diagrames no es renderitzen directament aquí, però el codi font es troba a docs/diagrams del repo original:

  • Entity-Relationship (BD)

    • diagrams/architecture/entity-relationship.mmd

  • Auth Flow

    • diagrams/flows/auth-flow.mmd

  • Search Flow (cerca ball ↔ cançó)

    • diagrams/flows/search-flow.mmd

  • Context (C4)

    • diagrams/architecture/context.puml

  • User Journey

    • diagrams/flows/user-journey.mmd

A mesura que la BD es redissenyi i s’afegeixin nous components (imports, events, etc.), caldrà:

  • Actualitzar aquests diagrames.
  • Actualitzar aquest document i, si cal, crear sub-docs específics.

Relació amb altres documents​

  • Visió del projecte: overview/vision
  • Tech stack: overview/tech-stack
  • Pla de redisseny de BD: architecture/db-redesign-plan
  • Sistema d’importació i enriquiment: architecture/import-system
  • Seguretat i JWT: architecture/security
  • Wizard d’events: architecture/events-wizard
  • Workflow de propietat: architecture/ownership-workflow