🏗️ Hexagonal Architecture in TypeScript - Modern Clean Code Example

Implementación profesional de Arquitectura Hexagonal (Ports & Adapters) en TypeScript para un sistema modular y altamente escalable.

📐 Diagrama de Arquitectura

graph TD
    A[API REST] -->|Express Adapter| B[Application]
    C[React UI] -->|HTTP Client| B
    D[Database] -->|TypeORM Adapter| B
    B -->|Ports| E[Domain Core]
    style E fill:#4B0082,stroke:#333,color:white

🧩 Dominio Principal (Core Business)

// Dominio: User entity (domain/user.ts)
export interface UserRepository {  // Puerto
  findById(id: string): Promise<User>;
  save(user: User): Promise<void>;
}

export class User {
  constructor(
    public readonly id: string,
    public name: string,
    public email: string
  ) {}
  
  updateName(newName: string): void {
    if (!newName) throw new Error("Invalid name");
    this.name = newName;
  }
}

🚀 Primeros Pasos

Requisitos

• Node.js 18+
• npm 9+
• TypeScript 5.0+

# Clonar e instalar dependencias
git https://github.com/IngridBianchi/Hexagonal-architecture.git
cd hexagonal-architecture
npm install

# Compilar y ejecutar
npm run build
npm start

🧪 Testing Strategy

# Ejecutar tests unitarios
npm test

# Tests con cobertura
npm run test:coverage

🏛️ Estructura del Proyecto

hexagonal-architecture/
├── src/
│   ├── domain/                 # Núcleo del negocio
│   │   ├── entities/           # Modelos de dominio
│   │   ├── ports/              # Interfaces principales
│   │   └── services/           # Lógica de negocio
│   ├── application/            # Casos de uso
│   ├── infrastructure/         # Implementaciones concretas
│   │   ├── adapters/           # TypeORM/Express adapters
│   │   ├── config/             # Configuraciones
│   │   └── server.ts           # Entry point
├── tests/                      # Pruebas unitarias
├── package.json                # Dependencias
└── tsconfig.json               # Config TypeScript

🔧 Stack Tecnológico

• Core: TypeScript 5.0
• API: Express.js
• ORM: TypeORM
• Testing: Jest + TS-Jest
• DI: TypeDI
• Validación: Zod
• Linting: ESLint + Prettier

🌟 Features Clave

✅ Tipado Estático Avanzado con TypeScript
✅ Inversión de Dependencias mediante interfaces
✅ Mocks Automáticos para testing de componentes
✅ Configuración Escalable con TypeDI
✅ Validación Estricta de entradas con Zod

🛠️ Workflow de Desarrollo

# Modo desarrollo (watch mode)
npm run dev

# Linting y formateo
npm run lint
npm run format

# Build para producción
npm run build

🤝 Guía de Contribución

1. Crea un fork del repositorio
2. Sigue la convención de commits convencionales
3. Mantén cobertura de tests > 90%
4. Actualiza la documentación correspondiente
5. Abre un PR con descripción detallada