# Arquitectura del Sistema

## Visión General

Swift Converter es una API REST que recibe mensajes bancarios en formato SWIFT MT940/MT950 y los convierte al estándar ISO 20022 camt.053.001.02 (XML).

## Stack Tecnológico

| Componente | Tecnología | Versión |
|---|---|---|
| Framework API | FastAPI | 0.111.0 |
| Servidor ASGI | Uvicorn | 0.29.0 |
| Base de datos | SQLite (dev) / PostgreSQL (prod) | SQLAlchemy 2.0 |
| Autenticación | JWT (python-jose) + API Keys (passlib/bcrypt) | HS256 |
| Rate Limiting | slowapi (Redis-compatible) | 0.1.9 |
| Validación XML | lxml + XSD propio | 5.2.2 |
| Configuración | pydantic-settings | 2.2.1 |

## Estructura de Carpetas

```
swift-converter/
├── app/
│   ├── main.py              # Punto de entrada FastAPI, middleware, rutas
│   ├── config.py            # Variables de entorno via pydantic-settings
│   ├── security/
│   │   ├── auth.py          # bcrypt hashing, JWT encode/decode
│   │   ├── rate_limit.py    # slowapi limiter con key por cliente
│   │   └── dependencies.py  # FastAPI dependencies: API Key, JWT, Admin
│   ├── routers/
│   │   ├── health.py        # GET /health (público)
│   │   ├── auth.py          # POST /auth/token
│   │   ├── convert.py       # POST /convert
│   │   └── admin.py         # CRUD de clientes + logs
│   ├── services/
│   │   ├── mt940_parser.py  # Parser de campos MT940/MT950
│   │   ├── camt053_mapper.py # Generador XML camt.053 con lxml
│   │   └── xsd_validator.py  # Validación contra XSD
│   ├── models/
│   │   ├── database.py      # Engine SQLAlchemy, SessionLocal, Base
│   │   ├── client.py        # Tabla clients (API Keys hasheadas)
│   │   └── audit.py         # Tabla audit_log (trazabilidad)
│   └── schemas/
│       └── api.py           # Pydantic models: request/response shapes
├── schemas/
│   └── camt.053.001.02.xsd  # XSD oficial ISO 20022
├── tests/
│   ├── conftest.py          # Fixtures: TestClient, BD en memoria
│   ├── test_auth.py         # Tests de autenticación y rate limiting
│   ├── test_convert.py      # Tests end-to-end de conversión
│   └── fixtures/
│       └── sample.mt940     # Mensaje MT940 de prueba (3 transacciones)
├── docs/                    # Esta documentación
├── .env                     # Variables de entorno (NO commitear)
├── .env.example             # Plantilla de variables
├── Dockerfile               # Imagen Python 3.11-slim
└── requirements.txt         # Dependencias Python
```

## Flujo de una Conversión

```
Cliente HTTP
    │
    ├─► POST /api/v1/auth/token (API Key → JWT)
    │
    └─► POST /api/v1/convert (Bearer JWT)
            │
            ├── get_jwt_client() → verifica JWT + BD
            ├── MT940Parser.parse() → dict Python
            ├── Camt053Mapper.map() → XML string
            ├── XSDValidator.validate() → bool + errores
            ├── AuditLog → BD (async-style, best-effort)
            └── Response(application/xml) + headers X-*
```

## Seguridad

- **API Keys**: nunca almacenadas en plano — solo el hash bcrypt.
- **JWT**: HS256, expira en 15 minutos por defecto.
- **Rate Limiting**: por cliente (extraído del JWT o API Key prefix) — no por IP.
- **Soft Delete**: los clientes eliminados quedan en BD con `deleted_at` y `active=False`.
- **Admin**: protegido por header `X-Admin-Secret` — cambiar en producción.

## Base de Datos

Dos tablas:

### `clients`
Almacena credenciales y configuración de cada cliente API.

### `audit_log`
Registra cada llamada a `/convert` con duración, estado, IP y detalle de error si aplica. Sirve como trazabilidad financiera y debugging.