Architecture Arquitectura

Jan 1, 2025

Hexagonal ArchitectureArquitectura Hexagonal

Firelands implements Hexagonal Architecture (also known as Ports & Adapters) to keep business logic decoupled from external systems.

Firelands implementa la Arquitectura Hexagonal (también conocida como Ports & Adapters) para mantener la lógica de negocio desacoplada de los sistemas externos.

Layer StructureEstructura de Capas

src/
├── shared/           # Common utilities, Logger, Common.h
├── domain/           # Entities, Value Objects, Repository Interfaces (Ports)
├── application/      # Use cases, Application Services
├── infrastructure/   # MySQL adapters, REST adapters, External wrappers (Adapters)
├── auth/            # Auth server executable
├── world/           # World server executable
└── tools/           # DevTools executable

Common utilities / Entities, Value Objects, Repository Interfaces (Ports)

Utilidades comunes / Entidades, Objetos de Valor, Interfaces de Repositorio (Ports)

Dependency RuleRegla de Dependencias

domain/ must NOT import from application/ or infrastructure/
All external dependencies flow inward: infrastructure → application → domain
Communication via abstract interfaces (ports)

domain/ debe NO importar de application/ o infrastructure/
Todas las dependencias externas fluyen hacia adentro: infrastructure → application → domain
Comunicación a través de interfaces abstractas (ports)

Domain Layer (`src/domain/`)Capa de Dominio (`src/domain/`)

Contains:

Entities: Core business objects
Value Objects: Immutable types
Repository Interfaces (Ports): Abstract interfaces for data access

Example:

domain/models/Character.h
domain/models/SpellDefinition.h
domain/models/GmTicket.h

Contiene:

Entidades: Objetos de negocio principales
Objetos de Valor: Tipos inmutables
Interfaces de Repositorio (Ports): Interfaces abstractas para acceso a datos

Ejemplo:

domain/models/Character.h
domain/models/SpellDefinition.h
domain/models/GmTicket.h

Application Layer (`src/application/`)Capa de Aplicación (`src/application/`)

Contains:

Services: Use cases implementing business logic
Ports: Interfaces defining external system interactions

Example:

application/services/AuthService.h
application/services/CharacterService.h
application/services/CommandService.h

Contiene:

Servicios: Casos de uso que implementan lógica de negocio
Ports: Interfaces que definen interacciones con sistemas externos

Ejemplo:

application/services/AuthService.h
application/services/CharacterService.h
application/services/CommandService.h

Infrastructure Layer (`src/infrastructure/`)Capa de Infraestructura (`src/infrastructure/`)

Contains:

Adapters: Implementations of ports
External wrappers: Third-party library wrappers

Contiene:

Adapters: Implementaciones de los ports
Wrappers externos: Wrappers de librerías de terceros

ExecutablesEjecutables

Target	Binary	Purpose
`auth`	`build/bin/auth`	Authentication server
`world`	`build/bin/world`	Game server

Objetivo	Binario	Propósito
`auth`	`build/bin/auth`	Servidor de autenticación
`world`	`build/bin/world`	Servidor de juego

Precompiled Headers (PCH)Encabezados Precompilados (PCH)

Heavy headers precompiled for faster builds:

STL containers
spdlog
nlohmann/json
shared/Common.h
shared/Logger.h

When adding new targets, include PCH:

target_precompile_headers(<target_name> PRIVATE ${PROJECT_PCH_HEADERS})

Important: spdlog MUST be included via <shared/Logger.h> for SPDLOG_LEVEL_NAMES to apply.

Encabezados pesados precompilados para construcciones más rápidas:

Contenedores STL
spdlog
nlohmann/json
shared/Common.h
shared/Logger.h

Al agregar nuevos objetivos, incluir PCH:

target_precompile_headers(<target_name> PRIVATE ${PROJECT_PCH_HEADERS})

Importante: spdlog DEBE ser incluido vía <shared/Logger.h> para que SPDLOG_LEVEL_NAMES aplique.