# 02 — Arquitectura general

## Vista de alto nivel

```mermaid
flowchart TB
    subgraph usuarios [Usuarios]
        WEB_USR[Navegador - sitio web]
        DEV_USR[Apps / otros sitios]
    end

    subgraph edge [Borde CDN]
        CF[CloudFront]
    end

    subgraph storage [Almacenamiento público]
        S3[(S3 Bucket)]
        S3_DATA[data/*.json]
        S3_WEB[index.html, js/, css/]
        S3_FOTOS[fotos/]
    end

    subgraph api_layer [Capa API]
        APIGW[API Gateway HTTP API]
        LAMBDA_API[Lambda vtb-terremoto-api]
    end

    subgraph data_layer [Capa de datos]
        DDB[(DynamoDB)]
        LAMBDA_EXPORT[Lambda vtb-terremoto-export]
    end

    WEB_USR -->|GET datos, assets| CF
    CF --> S3
    S3 --> S3_DATA
    S3 --> S3_WEB
    S3 --> S3_FOTOS

    WEB_USR -->|POST/PATCH formularios| APIGW
    DEV_USR -->|GET/POST /v1/* + API key| APIGW
    APIGW --> LAMBDA_API
    LAMBDA_API --> DDB
    LAMBDA_API -->|invoke async| LAMBDA_EXPORT
    LAMBDA_EXPORT --> DDB
    LAMBDA_EXPORT -->|put JSON| S3
    LAMBDA_API -->|presigned PUT| S3_FOTOS
```

## Principio fundamental: lectura y escritura separadas

| Operación | Ruta | Por qué |
|-----------|------|---------|
| **Leer** (listados, búsqueda) | CloudFront → S3 JSON | Millones de requests cacheables en edge |
| **Escribir** (reportar) | API Gateway → Lambda → DynamoDB | Consistencia, validación, auth |
| **Sincronizar** | Lambda export → S3 | Publicar cambios para lectores |

## Flujo de lectura (sitio web)

```
1. Usuario abre https://d2s8ujt32olfq2.cloudfront.net
2. Carga index.html, CSS, JS desde CloudFront
3. JS descarga en paralelo:
   - data/metadata.json        (~500 bytes) → estadísticas
   - data/desaparecidos/listing-recent.json  (~60 KB gzip) → últimos 500 registros
4. Renderiza grid de tarjetas (paginación en cliente)
5. En background: descarga listing.json completo si hace falta búsqueda/filtros
6. Segunda visita: localStorage cache → casi instantáneo
```

Ver [08-rendimiento.md](08-rendimiento.md) para benchmarks.

## Flujo de escritura (reportar persona)

```
1. Usuario llena formulario en el sitio
2. Si hay foto: POST /upload-url → PUT directo a S3 (presigned)
3. POST /desaparecidos → Lambda → DynamoDB PutItem
4. Lambda invoca export (async, Event)
5. Export escanea DynamoDB, regenera JSON en S3 (~5–60 s según volumen)
6. Usuario ve el registro tras invalidar caché / esperar export
```

## Flujo de integración (desarrollador externo)

```
1. Operador crea API key: scripts/create_api_key.py
2. Desarrollador lee masivamente: GET listing.json desde S3 (sin API)
3. Desarrollador escribe: POST /v1/desaparecidos con X-API-Key
4. Campo "fuente" identifica su sitio en el registro unificado
```

## Componentes y responsabilidades

| Componente | Archivo / recurso | Responsabilidad |
|------------|-------------------|-----------------|
| Frontend | `web/` | UI, lectura S3, escritura API legacy |
| API handler | `api/handler.py` | Rutas HTTP, auth, CRUD |
| API reads | `api/reads.py` | Consultas paginadas DynamoDB |
| API auth | `api/auth.py` | Validación API keys |
| Export | `api/export.py` | DynamoDB → S3 JSON |
| OpenAPI | `api/openapi.py` | Spec `/v1/docs` |
| Infra | `infrastructure/cloudformation.yaml` | Todos los recursos AWS |
| Deploy | `scripts/deploy.sh` | Empaquetar, desplegar, subir web |

## Dos APIs en un solo Lambda

| Prefijo | Autenticación | Uso |
|---------|---------------|-----|
| `/v1/*` | API key (`read` / `write`) | Integradores, documentada |
| `/desaparecidos`, `/sos`, etc. | Sin key | Sitio oficial legacy |

Ver [09-seguridad.md](09-seguridad.md).

## Escalabilidad

| Carga | Comportamiento |
|-------|----------------|
| 10.000 usuarios leyendo | CloudFront sirve JSON cacheado; origen S3 casi sin tráfico |
| 1.000 reportes/hora | DynamoDB on-demand absorbe writes; export cada 5 min + tras cada write |
| 50 integradores con API | API Gateway + Lambda escalan automáticamente |

## Costos estimados (orden de magnitud)

Con ~6.500 registros y tráfico de emergencia moderado: **~$60–150 USD/mes** (S3, CloudFront, Lambda, DynamoDB, API Gateway).

## Archivos de infraestructura alternativos

- `infrastructure/cloudformation.yaml` — **usado en producción** (deploy.sh)
- `infrastructure/template.yaml` — plantilla SAM original (no requiere SAM CLI si usas cloudformation.yaml)