El Architect: Arquitectura Tecnica

El Architect: System Founder

El Architect es el tercer agente en el flujo de BMAD. Su rol es transformar los requisitos del PRD en decisiones tecnicas concretas: que tecnologias usar, como estructurar el sistema, como se comunican los componentes y como se almacenan los datos.

Se le llama System Founder porque establece los cimientos sobre los que todo el codigo se construira.

Como carga el Architect los requisitos

El Architect recibe como input los artefactos del PM:

@docs/prd.md
@docs/epics.md
@docs/user-stories/

Analiza cada requisito funcional y no funcional para tomar decisiones de arquitectura fundamentadas. No inventa: justifica cada eleccion en base a los requisitos.

Artefactos que genera el Architect

Esta fase produce cuatro documentos clave:

Artefacto	Proposito
tech-stack.md	Tecnologias elegidas con justificacion
ARCHITECTURE.md	Disenio del sistema, componentes y patrones
db-schema.md	Esquema de base de datos con relaciones
api-spec.json	Especificacion de endpoints REST

Cada documento es un contrato. El Developer no puede usar una libreria que no este en tech-stack.md ni crear una tabla que no este en db-schema.md.

Tech Stack del Kanban

El Architect evalua opciones y documenta sus decisiones:

Backend:

Aspecto	Eleccion	Justificacion
Lenguaje	Node.js + TypeScript	Ecosistema maduro, tipado estatico, equipo familiarizado
Framework	Express.js	Minimalista, amplia comunidad, suficiente para API REST
ORM	Prisma	Type-safe, migraciones automaticas, excelente DX
Auth	JWT + bcrypt	Stateless, escalable, FR-01 requiere sesiones

Frontend:

Aspecto	Eleccion	Justificacion
Framework	React 18	Componentes declarativos, ecosistema de drag & drop
Drag & Drop	@dnd-kit	Accesible (NFR-03), ligero, API moderna
Estado	Zustand	Simple, sin boilerplate, suficiente para MVP
Estilos	Tailwind CSS	Utility-first, rapido de prototipar

Infraestructura:

Aspecto	Eleccion	Justificacion
Base de datos	PostgreSQL	Relacional, ACID, soporta las relaciones boards→columns→cards
Contenedores	Docker + docker-compose	Entorno reproducible, deployment consistente
Testing	Vitest + Playwright	Unit tests rapidos, E2E para drag & drop

Cada fila tiene una justificacion que referencia un requisito o una restriccion. No se elige “porque si”.

ARCHITECTURE.md: Disenio del Sistema

El documento principal de arquitectura incluye un diagrama de componentes:

graph TD
    Client[React SPA] -->|HTTP/REST| API[Express API]
    API -->|Prisma ORM| DB[(PostgreSQL)]
    API -->|JWT| Auth[Auth Middleware]
    Auth -->|Valida token| API
    Client -->|Drag events| DnD[@dnd-kit]
    DnD -->|PATCH /cards/:id| API

Patron arquitectonico: El Architect elige una estructura modular por dominio, separando responsabilidades:

backend/
  src/
    modules/
      auth/          ← Registro, login, JWT
        controller.ts
        service.ts
        routes.ts
      boards/        ← CRUD de tableros
        controller.ts
        service.ts
        routes.ts
      columns/       ← Logica de columnas
        controller.ts
        service.ts
        routes.ts
      cards/         ← CRUD y movimiento de tarjetas
        controller.ts
        service.ts
        routes.ts
    middleware/
      auth.ts        ← Verificacion JWT
      error.ts       ← Manejo global de errores
    prisma/
      schema.prisma  ← Esquema de datos
    app.ts           ← Configuracion Express
    server.ts        ← Entry point

frontend/
  src/
    components/
      Board/
      Card/
      Column/
      Auth/
    stores/
    hooks/
    api/             ← Llamadas HTTP al backend

Cada modulo tiene tres capas: controller (recibe HTTP), service (logica de negocio) y routes (define endpoints). Esta separacion cumple con el principio de responsabilidad unica.

Esquema de Base de Datos

El db-schema.md define las tablas y sus relaciones:

erDiagram
    users {
        uuid id PK
        string email UK
        string password_hash
        string name
        timestamp created_at
    }
    boards {
        uuid id PK
        string name
        uuid owner_id FK
        timestamp created_at
        timestamp updated_at
    }
    columns {
        uuid id PK
        string name
        int position
        uuid board_id FK
    }
    cards {
        uuid id PK
        string title
        text description
        enum priority
        int position
        uuid column_id FK
        uuid assigned_to FK
        timestamp created_at
        timestamp updated_at
    }

    users ||--o{ boards : "owns"
    boards ||--o{ columns : "has"
    columns ||--o{ cards : "contains"
    users ||--o{ cards : "assigned_to"

Decisiones de disenio:

• UUIDs como primary keys: evita colisiones y es seguro en URLs
• position (integer) en columns y cards: permite reordenar con drag & drop
• priority como enum: low, medium, high — valores acotados, no texto libre
• password_hash: nunca se almacena el password en texto plano (NFR-02)
• Soft delete no incluido en MVP: se elimina fisicamente por simplicidad

Especificacion de API REST

El Architect define los endpoints que el Developer implementara:

Autenticacion:

Metodo	Endpoint	Descripcion	Auth
POST	/api/auth/register	Registrar usuario	No
POST	/api/auth/login	Obtener JWT	No

Tableros:

Metodo	Endpoint	Descripcion	Auth
GET	/api/boards	Listar tableros del usuario	Si
POST	/api/boards	Crear tablero	Si
GET	/api/boards/:id	Detalle con columnas y tarjetas	Si
PUT	/api/boards/:id	Actualizar nombre	Si
DELETE	/api/boards/:id	Eliminar tablero	Si

Columnas:

Metodo	Endpoint	Descripcion	Auth
POST	/api/boards/:boardId/columns	Crear columna	Si
PATCH	/api/columns/:id/position	Reordenar columna	Si

Tarjetas:

Metodo	Endpoint	Descripcion	Auth
POST	/api/columns/:columnId/cards	Crear tarjeta	Si
PUT	/api/cards/:id	Actualizar tarjeta	Si
DELETE	/api/cards/:id	Eliminar tarjeta	Si
PATCH	/api/cards/:id/move	Mover a otra columna	Si

Cada endpoint documenta: metodo, ruta, cuerpo esperado, respuesta exitosa y codigos de error. El Developer no necesita adivinar nada.

Decisiones y trade-offs

El Architect documenta explicitamente lo que descarto y por que:

Descartado	Razon
GraphQL	Overhead innecesario para un CRUD simple
MongoDB	Las relaciones boards→columns→cards favorecen SQL
WebSockets	Fuera del MVP, se agrega en v2.0 si se necesita
Microservicios	Un monolito modular es suficiente para el MVP
Redis	Sin cache en MVP, PostgreSQL maneja la carga esperada

Estas decisiones evitan discusiones futuras. Si alguien pregunta “¿por que no usamos GraphQL?”, la respuesta ya esta documentada.

Versionado en Git

Todos los artefactos del Architect se commitean al repositorio:

git add docs/tech-stack.md docs/ARCHITECTURE.md docs/db-schema.md docs/api-spec.json
git commit -m "docs: arquitectura tecnica del Kanban - Fase 3 BMAD"

Si durante el desarrollo se necesita un cambio arquitectonico (nueva tabla, nuevo endpoint), se actualiza primero el documento y luego el codigo. El documento es la fuente de verdad.

Revision humana

Al igual que con el PRD, el humano revisa antes de avanzar:

• ¿El tech stack es adecuado para tu equipo y contexto?
• ¿El esquema de DB cubre todos los requisitos funcionales?
• ¿Los endpoints de la API son coherentes?
• ¿Las decisiones descartadas tienen sentido?

Solo con tu aprobacion, el Scrum Master puede comenzar a fragmentar el trabajo en stories.

---

← Capitulo 4: El Product Manager | Capitulo 6: El Scrum Master →