hackathon-opti-1a67c90779374919b2f9ca0914dcd4b4/backend/ARCHITECTURE.md

# Clean Architecture - Backend OptiHack

## Estructura del Proyecto

```
src/
├── config/              # Configuración e integración con librerías
│   ├── env.ts          # Variables de entorno
│   ├── jwt.ts          # JwtAdapter - genera y valida tokens
│   └── bcrypt.ts       # BcryptAdapter - hashea y compara contraseñas
│
├── domain/             # Lógica de negocio (sin dependencias externas)
│   ├── dtos/           # Data Transfer Objects con validación
│   │   ├── auth/
│   │   │   ├── register-user.dto.ts
│   │   │   └── login-user.dto.ts
│   │   └── index.ts
│   │
│   ├── repositories/   # Interfaces de repositorios (contratos)
│   │   └── auth.repository.ts
│   │
│   ├── use-cases/      # Lógica de negocio (casos de uso)
│   │   └── auth/
│   │       ├── register-user.use-case.ts
│   │       ├── login-user.use-case.ts
│   │       └── get-me.use-case.ts
│   │
│   └── errors/         # Errores personalizados
│       └── custom.error.ts
│
├── data/               # Implementación de datos (Prisma, BD)
│   ├── postgres/       # Cliente de Prisma
│   │   └── index.ts
│   └── repositories/   # Implementación de repositorios
│       └── auth.repository.impl.ts
│
├── presentation/       # HTTP (Express, controladores, middlewares)
│   ├── auth/
│   │   ├── controller.ts
│   │   └── routes.ts
│   ├── middlewares/
│   │   └── auth.middleware.ts
│   ├── routes.ts       # Rutas principales
│   └── server.ts       # Instancia de Express
│
├── app.ts              # Punto de entrada
└── ...
```

## Flujo de Datos (Regla Principal)

```
HTTP Request
    ↓
Controller recibe los datos
    ↓
Controller llama al UseCase
    ↓
UseCase hace la lógica de negocio
    ↓
UseCase llama al Repository
    ↓
Repository implementación habla con Prisma
    ↓
Prisma ejecuta queries en la BD
    ↓
Response va hacia arriba
    ↓
HTTP Response
```

### Ejemplo: Register

1. **Cliente** envía POST `/api/auth/register` con `{ name, email, password }`
2. **Controller** recibe la request
3. **Controller** llama a `RegisterUserUseCase.execute()`
4. **UseCase** valida el DTO
5. **UseCase** verifica si el email existe (llama al Repository)
6. **Repository** busca en la BD
7. **UseCase** hashea la contraseña
8. **UseCase** crea el usuario (llama al Repository)
9. **Repository** inserta en la BD
10. **UseCase** genera el JWT
11. **Controller** responde con user + token

## Responsabilidades por Capa

### **Config**
- Variables de entorno
- Adapters (JWT, Bcrypt)
- Configuraciones globales

### **Domain** (Sin dependencias externas)
- DTOs con validación
- Interfaces de repositorios (contratos)
- Casos de uso (lógica de negocio)
- Errores personalizados

### **Data**
- Implementación de repositorios
- Cliente de Prisma
- Queries a la base de datos

### **Presentation**
- Controladores (Express handlers)
- Rutas
- Middlewares
- Validación HTTP

## Endpoints de Autenticación

### 1. Register
```
POST /api/auth/register
Content-Type: application/json

{
  "name": "John Doe",
  "email": "john@example.com",
  "password": "password123"
}

Response 201:
{
  "user": {
    "id": 1,
    "email": "john@example.com",
    "name": "John Doe"
  },
  "token": "eyJhbGc..."
}
```

### 2. Login
```
POST /api/auth/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "password123"
}

Response 200:
{
  "user": {
    "id": 1,
    "email": "john@example.com",
    "name": "John Doe"
  },
  "token": "eyJhbGc..."
}
```

### 3. GetMe (Protegida)
```
GET /api/auth/me
Authorization: Bearer eyJhbGc...

Response 200:
{
  "id": 1,
  "email": "john@example.com",
  "name": "John Doe",
  "role": "USER"
}
```

## Validaciones

### DTOs
- **name**: string no vacío
- **email**: email válido (regex)
- **password**: mínimo 6 caracteres

### Errores
- **400 Bad Request**: Datos inválidos
- **401 Unauthorized**: Token inválido, usuario no autenticado
- **404 Not Found**: Usuario no encontrado
- **409 Conflict**: Email ya en uso
- **500 Internal Server Error**: Error del servidor

## Variables de Entorno (.env)

```
PORT=3000                                              # Puerto del servidor
NODE_ENV=development                                   # Entorno
DATABASE_URL=postgresql://user:pass@host:5432/db      # URL de BD
JWT_SEED=tu_secreto_super_seguro                       # Seed para JWT
JWT_EXPIRES_IN=7d                                      # Expiración del token
BCRYPT_ROUNDS=10                                       # Rondas de bcrypt
```

## Cómo Agregar un Nuevo UseCase

1. **Crear el UseCase** en `domain/use-cases/auth/new-feature.use-case.ts`
2. **Agregar método al Repository** en `domain/repositories/auth.repository.ts`
3. **Implementar en** `data/repositories/auth.repository.impl.ts`
4. **Crear método en Controller** en `presentation/auth/controller.ts`
5. **Agregar ruta** en `presentation/auth/routes.ts`

## Ventajas de Esta Arquitectura

✓ **Separación de responsabilidades**: Cada capa hace una cosa
✓ **Fácil de testear**: UseCase no conoce HTTP ni BD
✓ **Mantenible**: Cambios en BD no afectan lógica de negocio
✓ **Escalable**: Fácil agregar nuevos módulos
✓ **Simple**: No over-engineered, ideal para MVP/Hackathon
✓ **Limpio**: Código organizado y fácil de entender