# ARCHITECTURE: Arquitectura Propuesta — [Nombre del Proyecto]

> Documento de diseño arquitectural. Define la estructura del sistema antes
> de escribir código. Las decisiones aquí deben estar respaldadas por ADRs
> para las más significativas.
> Autor: [nombre] | Fecha: YYYY-MM-DD | Estado: Borrador / Revisado / Aprobado

---

## Visión general

[2-3 párrafos describiendo la arquitectura en términos de alto nivel.
Qué tipo de sistema es (monolito modular, microservicios, serverless, etc.).
Por qué esta estructura es la correcta para este problema y equipo.]

**Estilo arquitectural**: [ej. Monolito modular con frontend SPA]
**Patrón principal**: [ej. Layered Architecture / Hexagonal / CQRS]
**Justificación**: [Por qué este estilo y no otro para este proyecto]

---

## Diagrama de contexto (Nivel 1 — C4)

```
┌─────────────────────────────────────────────────────────────────┐
│                        Sistema: [Nombre]                        │
│                                                                  │
│  ┌──────────┐    HTTPS     ┌──────────────────┐                │
│  │ Usuario  │ ──────────► │  Frontend SPA    │                │
│  │          │ ◄────────── │  (Angular)       │                │
│  └──────────┘              └────────┬─────────┘                │
│                                     │ REST API                  │
│                            ┌────────▼─────────┐                │
│                            │   Backend API    │                │
│                            │   (FastAPI)      │                │
│                            └──┬────────────┬──┘                │
│                               │            │                    │
│                    ┌──────────▼──┐  ┌──────▼──────────┐       │
│                    │ PostgreSQL  │  │ Redis (cache)   │       │
│                    │    (BD)     │  │                 │       │
│                    └─────────────┘  └─────────────────┘       │
└─────────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
   ┌──────▼──────┐  ┌─────────▼──────┐  ┌────────▼────────┐
   │ [Servicio   │  │ [API Externa   │  │ [Servicio de    │
   │  Externo 1] │  │  ej. SAT CFDI] │  │  Email / SMS]   │
   └─────────────┘  └────────────────┘  └─────────────────┘
```

[Actualizar el diagrama con los componentes reales del proyecto]

---

## Diagrama de contenedores (Nivel 2 — C4)

```
┌─────────────────────────────────────────────────────────┐
│                     Backend API                         │
│                                                          │
│  ┌─────────────┐   ┌─────────────┐   ┌──────────────┐  │
│  │  Routers    │──►│  Services   │──►│ Repositories │  │
│  │ (endpoints) │   │ (lógica de  │   │ (acceso a    │  │
│  │             │◄──│  negocio)   │◄──│  datos)      │  │
│  └─────────────┘   └──────┬──────┘   └──────┬───────┘  │
│                            │                 │           │
│                    ┌───────▼───────┐  ┌──────▼──────┐   │
│                    │ Domain Models │  │    ORM      │   │
│                    │ (Pydantic)    │  │ (SQLAlchemy)│   │
│                    └───────────────┘  └─────────────┘   │
└─────────────────────────────────────────────────────────┘
```

---

## Módulos del sistema

### Módulo: [Nombre — ej. Autenticación]

**Responsabilidad**: [Qué problema resuelve este módulo y nada más]
**Interfaz pública**:
- `POST /auth/login` — obtener token JWT
- `POST /auth/refresh` — renovar token
- `POST /auth/logout` — invalidar token
- `AuthGuard` — guardia de Angular para rutas protegidas

**Lo que NO hace este módulo**:
- [Restricción explícita — qué responsabilidad NO tiene]

**Archivos principales**:
```
backend/app/
├── routers/auth.py
├── services/auth_service.py
├── models/usuario.py
└── schemas/auth.py

frontend/src/app/
├── core/guards/auth.guard.ts
└── features/auth/
    ├── login/
    └── services/auth.service.ts
```

---

### Módulo: [Nombre — ej. Gestión de Facturas]

**Responsabilidad**:
**Interfaz pública**:
- `GET /facturas` — listar facturas del usuario
- `POST /facturas` — crear factura
- `GET /facturas/{id}` — detalle
- `PUT /facturas/{id}/timbrar` — enviar al PAC

**Lo que NO hace este módulo**:
-

**Archivos principales**:
```
backend/app/
├── routers/facturas.py
├── services/factura_service.py
├── models/factura.py
└── schemas/factura.py

frontend/src/app/features/facturas/
├── list/
├── form/
└── services/facturas.service.ts
```

---

### Módulo: [Nombre del tercer módulo]

**Responsabilidad**:
**Interfaz pública**:
-

---

## Flujos de datos principales

### Flujo 1: [ej. Creación de factura]

```
Usuario                Frontend              Backend API           BD
  │                       │                      │                  │
  │── Llena formulario ──►│                      │                  │
  │                       │── POST /facturas ───►│                  │
  │                       │                      │── Valida schema  │
  │                       │                      │── Crea registro ►│
  │                       │                      │◄─ Retorna ID ────│
  │                       │◄── 201 { factura } ──│                  │
  │◄── Redirige al detalle│                      │                  │
```

### Flujo 2: [ej. Autenticación con JWT]

```
Usuario                Frontend              Backend API           Redis
  │                       │                      │                   │
  │── Login (user/pass) ──►│                      │                   │
  │                       │── POST /auth/login ──►│                   │
  │                       │                      │── Verifica creds  │
  │                       │                      │── Genera JWT      │
  │                       │◄── 200 { token } ────│                   │
  │                       │── Guarda en storage   │                   │
  │◄─ Redirige al dashboard│                      │                   │
```

---

## Decisiones arquitecturales clave

| Decisión | Descripción | ADR |
|----------|-------------|-----|
| [Título de la decisión] | [Qué se decidió en una línea] | ADR-NNN |
| [Título de la decisión] | | ADR-NNN |
| [Título de la decisión] | | ADR-NNN |

---

## Estrategia de autenticación y autorización

**Autenticación**: [ej. JWT con refresh tokens en httpOnly cookie]
**Autorización**: [ej. RBAC con roles: ADMIN, OPERADOR, LECTOR]
**Roles definidos**:

| Rol | Descripción | Permisos |
|-----|-------------|----------|
| [ADMIN] | [descripción] | [CRUD completo] |
| [OPERADOR] | [descripción] | [Crear y editar, no eliminar] |
| [LECTOR] | [descripción] | [Solo lectura] |

---

## Estrategia de errores

| Tipo de error | HTTP Status | Formato de respuesta |
|---------------|-------------|---------------------|
| Validación de input | 422 | `{ detail: [{ loc, msg, type }] }` (Pydantic default) |
| No autenticado | 401 | `{ detail: "No autenticado" }` |
| Sin permisos | 403 | `{ detail: "Sin permisos para esta operación" }` |
| Recurso no encontrado | 404 | `{ detail: "Recurso no encontrado" }` |
| Error de negocio | 400 | `{ detail: "descripción del error de negocio" }` |
| Error interno | 500 | `{ detail: "Error interno del servidor" }` (sin exponer stack) |

---

## Checklist de arquitectura

- [ ] Cada módulo tiene responsabilidad claramente definida
- [ ] No hay dependencias circulares entre módulos
- [ ] Los flujos de datos están documentados para los casos principales
- [ ] La estrategia de auth cubre autenticación y autorización
- [ ] Las decisiones significativas tienen ADRs pendientes de redactar
- [ ] La arquitectura es verificable con los criterios definidos en HOJA-RUTA.md
