Esta sección presenta la arquitectura general de SportApp para interesados técnicos y no técnicos. Resume la documentación detallada de arquitectura/ sin trasladar a la Wiki las instrucciones operativas destinadas al desarrollo con agentes.

Las vistas describen principalmente la arquitectura objetivo. Un elemento dibujado no se considera implementado hasta que exista código, prueba, despliegue o evidencia operativa enlazada.

flowchart LR
    ACT["Deportistas, organizadores,<br/>proveedores y administradores"]
    WEB["Aplicación web<br/>Angular"]
    MOB["Aplicación móvil<br/>Kotlin Android"]
    BFW[BFF web]
    BFM[BFF móvil]
    EDGE[API Gateway e Ingress]

    subgraph CORE[Microservicios por dominio]
      U[Usuarios]
      A[Afiliación]
      S[Servicios]
      T[Entrenamientos]
      E[Eventos]
      X[Terceros]
    end

    PS[Pub/Sub]
    DB[("PostgreSQL<br/>por dominio")]
    EXT[Strava y dispositivos]

    ACT --> WEB
    ACT --> MOB
    WEB --> BFW --> EDGE
    MOB --> BFM --> EDGE
    EDGE --> CORE
    CORE --> DB
    CORE <--> PS
    X <--> EXT
    MOB <--> EXT

1. Los microservicios se separan por dominio de negocio, no por pantalla.
2. Web y móvil consumen un BFF propio y no acceden directamente a servicios internos ni bases de datos.
3. Cada dominio es dueño de sus datos y no escribe en almacenes ajenos.
4. Las operaciones síncronas usan API versionadas; la colaboración asíncrona usa eventos versionados en Pub/Sub.
5. CQRS se aplica selectivamente a usuarios, entrenamientos y eventos.
6. Los cambios de escritura y sus eventos se confirman mediante outbox transaccional.
7. Strava y futuros terceros se aíslan detrás de adaptadores.
8. Backend, web, móvil y plataforma conservan versiones independientes; la plataforma fija una composición reproducible por sprint.

Backend, frontend web, móvil y plataforma aplican el mismo GitFlow, pero cada repositorio conserva sus propias ramas, commits, pull requests, CI y versión. Una rama de plataforma nunca contiene ni publica el código interno de otro componente.

flowchart TB
    subgraph NORMAL[Flujo normal]
      direction LR
      D["1. develop actualizado"] --> F["2. feature/HUxxx-descripcion"]
      F --> CI["3. push y CI"]
      CI --> PD["4. PR hacia develop"]
      PD --> RL["5. release/vX.Y.Z"]
      RL --> PM["6. PR hacia main"]
      PM --> TAG["7. tag vX.Y.Z"]
      RL -. correcciones .-> D
    end

    subgraph URGENTE[Flujo de hotfix]
      direction LR
      INC["Incidente en main o tag"] --> HF["1. hotfix/vX.Y.Z-descripcion"]
      HF --> HPR["2. PR hacia main"]
      HPR --> HT["3. nuevo tag PATCH"]
      HT --> RET["4. retorno a develop y release activa"]
    end

main contiene versiones liberadas; develop integra el siguiente sprint; feature/* implementa una HU; release/* estabiliza una versión sin agregar funcionalidades; y hotfix/* corrige urgentemente una versión publicada. Todas las integraciones a develop o main se realizan mediante pull request, CI y revisión. El flujo detallado, las responsabilidades y el manejo de una HU en varios repositorios están en Integración continua y releases.

flowchart TB
    P["sport-app-platform<br/>versión del sprint"]
    R["Manifiesto de composición<br/>tags, commits y artefactos"]
    B["sport-app-backend<br/>SemVer independiente"]
    W["sport-app-frontend<br/>SemVer independiente"]
    M["sport-app-movil<br/>SemVer y versionCode"]

    P --> R
    P -. submódulo .-> B
    P -. submódulo .-> W
    P -. submódulo .-> M
    R --> B
    R --> W
    R --> M

Nota — SemVer: significa Semantic Versioning o versionado semántico. Una versión se expresa como MAYOR.MENOR.PARCHE; por ejemplo, v2.3.1. MAYOR aumenta cuando existen cambios incompatibles, MENOR cuando se agregan funcionalidades compatibles y PARCHE cuando se publican correcciones compatibles. En SportApp cada repositorio conserva su propia versión, por lo que backend, frontend y móvil no tienen que compartir el mismo número. En Android, versionCode es adicionalmente un entero interno que siempre debe aumentar con cada publicación.

La síntesis de decisiones, fuentes y alcance se mantiene en Decisiones, fuentes y alcance.