PackmindHub/hexagonal-architecture

Hexagonal Architecture - Packmind Monorepo

Architecture Map

Every domain package follows a three-layer hexagonal (ports & adapters) architecture. Dependencies flow inward only: Infrastructure -> Application -> Domain.

packages/{domain}/src/
├── domain/                          # Pure business logic, zero dependencies
│   ├── entities/                    # Domain entities and value objects
│   ├── repositories/                # Repository interfaces (ports)
│   ├── jobs/                        # Delayed job definitions
│   ├── errors/                      # Domain-specific error classes
│   ├── utils/                       # Domain-specific utility functions
│   └── types/                       # Domain-specific type definitions
│
├── application/                     # Orchestration & coordination
│   ├── useCases/{name}/             # One folder per use case
│   │   └── {name}.usecase.ts
│   ├── services/                    # Domain services + service aggregator
│   ├── adapter/                     # Outbound adapter (implements port)
│   ├── listeners/                   # Domain event listeners
│   └── jobs/                        # Delayed job implementations
│
├── infra/                           # Concrete implementations
│   ├── repositories/                # Repository implementations (TypeORM)
│   ├── schemas/                     # TypeORM EntitySchema definitions
│   └── jobs/                        # Job factories
│
└── index.ts                         # Package exports + {Domain}Hexa facade

Layer Details

| Layer | Depends On | Purpose | Details | |-------|-----------|---------|---------| | Domain | Nothing (pure TS + @packmind/types) | Business rules, entity definitions, port interfaces | domain-layer.md | | Application | Domain | Use case orchestration, services, adapters, events | application-layer.md | | Infrastructure | Domain + Application | Persistence, schemas, job queues | infrastructure-layer.md |

Component Reference

Each component type has its own detailed guide with templates and examples:

| Component | Layer | File Pattern | Guide | |-----------|-------|-------------|-------| | Use Case | Application | application/useCases/{name}/{name}.usecase.ts | usecase.md | | Service | Application | application/services/{Name}Service.ts | service.md | | Adapter | Application | application/adapter/{Domain}Adapter.ts | adapter.md | | Port | Types package | packages/types/src/{domain}/ports/I{Domain}Port.ts | port.md | | Contract | Types package | packages/types/src/{domain}/contracts/{UseCaseName}.ts | contract.md | | Repository (interface) | Domain | domain/repositories/I{Entity}Repository.ts | repository.md | | Repository (impl) | Infrastructure | infra/repositories/{Entity}Repository.ts | repository.md | | Schema | Infrastructure | infra/schemas/{Entity}Schema.ts | schema.md | | Listener | Application | application/listeners/{Domain}Listener.ts | listener.md | | Event | Types package | packages/types/src/events/{EventName}.ts | event.md | | Hexa Facade | Root | {Domain}Hexa.ts + index.ts | hexa-facade.md |

Dependency Flow

  API (NestJS controllers)
         │
         ▼
  ┌─────────────┐
  │ HexaRegistry │  ── Central DI container
  └──────┬──────┘
         │ getAdapter<IXxxPort>(portName)
         ▼
  ┌─────────────┐
  │ {Domain}Hexa │  ── Facade: wires repos, services, adapter
  └──────┬──────┘
         │
    ┌────┴────┐
    ▼         ▼
 Adapter   Services  ── Application layer
    │         │
    ▼         ▼
 Use Cases ──► Domain entities + Repository interfaces
    │
    ▼
 Infra Repositories ── Concrete persistence (TypeORM)

Cross-Domain Communication

Domains talk to each other through two mechanisms:

1. Synchronous - Via ports injected through the HexaRegistry during initialize(). Example: StandardsAdapter calls IGitPort.commitToGit().

2. Asynchronous - Via domain events emitted through PackmindEventEmitterService. Example: StandardCreatedEvent triggers DeploymentsListener.handleStandardCreated().

See event.md and adapter.md for patterns.

Key Base Classes (from @packmind/node-utils)

| Class | Purpose | |-------|---------| | BaseHexa<TOpts, TPort> | Hexagon lifecycle (construct -> initialize -> destroy) | | HexaRegistry | Central dependency injection container | | AbstractMemberUseCase<C, R> | Use case with org member authorization | | AbstractSpaceMemberUseCase<C, R> | Use case with org + space member authorization | | AbstractAdminUseCase<C, R> | Use case with admin authorization | | AbstractRepository<T> | Base TypeORM repository with soft delete support | | PackmindListener<TAdapter> | Event subscription base class | | PackmindEventEmitterService | Event bus for domain events |