Proyecto Arquitectura y tecnologias - MiraPdS/mira GitHub Wiki

Proyecto - Arquitectura y tecnologías

Vista general

flowchart LR
  B[Navegador] -->|"/ y /api/*"| V["Vercel<br/>apps/web (React SPA)"]
  V -->|"rewrite /api/*"| R["Render<br/>apps/api (Express)"]
  R -->|Prisma| S[("Supabase<br/>PostgreSQL")]
  U[UptimeRobot] -.->|"/api/health cada 5 min"| V
Loading

El navegador ve un solo origen: Vercel reenvía /api a Render, así que la cookie de sesión es first-party y funciona también en Safari e incógnito (D13). Cómo se monta y se recrea: docs/despliegue.md.

Estructura del repositorio

Monorepo con npm workspaces (D1): una historia que toca frontend y backend es una rama, un PR y un item de Jira.

flowchart TB
  subgraph packages
    SH["shared<br/>esquemas Zod · tipos · can()"]
  end
  subgraph apps
    W["web<br/>React + Vite"]
    A["api<br/>Express + Prisma"]
  end
  W --> SH
  A --> SH
Loading

packages/shared es el contrato: el mismo esquema Zod valida el formulario de React y la petición en Express, y la misma función can(rol, permiso) decide qué se muestra en la interfaz y qué permite la API.

Capas del backend

Cada módulo (auth, projects, work-items, comments, health) sigue la misma cadena:

flowchart LR
  RT[router] --> C["controller<br/>(HTTP)"] --> SV["service<br/>(reglas)"] --> RP["repository<br/>(persistencia)"] --> P[(Prisma)]
Loading

El service recibe el repositorio por parámetro y lanza errores de dominio sin conocer Express ni Prisma. Esa es la decisión que hace barato probar: las reglas se verifican con un doble en milisegundos, y las rutas completas con Supertest contra un PostgreSQL real.

Tecnologías y su relación con las pruebas

Capa Tecnología Qué aporta a las pruebas
Frontend React 18 + TypeScript + Vite Vitest reutiliza la configuración de Vite: la app y sus pruebas se compilan igual
Estado de servidor TanStack Query Estados de carga y error explícitos, fáciles de asertar con RTL
Formularios react-hook-form + Zod El esquema que valida en la UI es el mismo que se prueba en shared
UI Tailwind CSS 4 + shadcn/ui Componentes con roles ARIA correctos: RTL los encuentra por rol y etiqueta
Tablero dnd-kit + menú "Mover a…" El menú da un camino determinista para RTL y para los E2E de la Entrega 3 (D9)
Backend Node 20 + Express + TypeScript app exportable sin abrir puerto: Supertest le hace peticiones directas
Base de datos PostgreSQL 16 (Docker local, Supabase desplegado) Un PostgreSQL idéntico y efímero en CI (D6)
ORM Prisma 6 Migraciones versionadas que se aplican igual en CI y en producción
Validación Zod (compartido) Una sola definición del contrato para tipos y runtime
Sesión JWT en cookie httpOnly Los E2E hacen login por la UI y el navegador arrastra la cookie (D3)
Pruebas Vitest + React Testing Library, Supertest, MSW, vitest-mock-extended Herramienta declarada del equipo. Ver Estrategia de pruebas
CI GitHub Actions Formato, lint, tipos, las tres suites y build en cada PR; check obligatorio de main (D11)
Despliegue Vercel + Render + Supabase URL pública estable: será la BASE_URL de los E2E (D12)

Decisiones técnicas

Cada decisión tiene su justificación y sus alternativas descartadas en docs/decisiones-tecnicas.md.

Decisión
D1 Monorepo con npm workspaces
D2 Supabase como PostgreSQL gestionado, con Prisma; sin supabase-js ni RLS
D3 JWT en cookie httpOnly
D4 Pirámide de dos niveles en el backend: unitario + integración
D5 Esquemas Zod compartidos como contrato de la API
D6 Docker local para desarrollo y pruebas; Supabase para lo desplegado
D7 Roles por proyecto y una función can() pura
D8 Estados del tablero como enum fijo
D9 Kanban con dnd-kit y un menú "Mover a…" obligatorio
D10 Historial escrito dentro de la misma transacción que el cambio
D11 GitHub Actions en la Entrega 1, Jenkins en la Entrega 2
D12 Despliegue en Vercel, Render y Supabase
D13 Mismo origen mediante rewrite de Vercel

Herramientas de IA

El equipo usa asistentes de IA como apoyo al desarrollo, con el mismo flujo que cualquier otro cambio: rama, PR, CI verde y revisión de otro integrante.

Herramienta Uso principal
Claude Code Planificación de items, implementación, revisión de PRs y documentación
Codex Segunda opinión en implementaciones y diagnóstico de fallos

Qué se generó con IA y cómo se validó se declara en cada PR y se resume por entrega, en la sección "Uso de IA" de cada página de entrega (Entrega 1).

⚠️ **GitHub.com Fallback** ⚠️