Agent skill

hexagonal-architecture

Describes the hexagonal architecture (ports and adapters) used across the Packmind monorepo. This skill should be used when creating new domain packages, use cases, services, repositories, or any architectural component to follow established patterns.

View SKILL.md on GitHub Repository
Stars 260
Forks 13

Install this agent skill to your Project

npx add-skill https://github.com/PackmindHub/packmind/tree/main/packages/.claude/skills/hexagonal-architecture

SKILL.md

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 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

PackmindHub/packmind

working-with-playground-app

This skill provides guidance for building UI/UX prototypes in the Packmind playground app. It should be used when creating a new prototype, iterating on an existing prototype, or working with files in apps/playground/. Triggers on mentions of "playground", "prototype", or direct work within the apps/playground/ directory.

260 13
Explore
PackmindHub/packmind

qa-review

Review a user story implementation against its Example Mapping (EM) specification.

260 13
Explore
PackmindHub/packmind

packmind-create-command

Guide for creating reusable commands via the Packmind CLI. This skill should be used when users want to create a new command that captures multi-step workflows, recipes, or task automation for distribution to CoPilot.

260 13
Explore
PackmindHub/packmind

doc-audit

Audit Packmind end-user documentation (apps/doc/) for broken links, outdated CLI references, non-existent concepts, misleading information, and missing coverage. Produces a structured markdown report at project root. Use when docs may have drifted from the codebase, before a release, or on a regular cadence.

260 13
Explore
PackmindHub/packmind

git-commit-guidelines

Enforce git commit best practices using gitmoji + Conventional Commits format. TRIGGER when creating commits. Ensures quality-gate passes, prevents issue auto-closing (no Close/Fix keywords), includes Co-Authored-By for AI commits, and requires user approval before committing.

260 13
Explore
PackmindHub/packmind

internal-comms

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

260 13
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results