How onicagroup/hexagonal-example works
Project type & purpose (what you’re diagramming)
This repo is a TypeScript reference implementation of Hexagonal (Ports & Adapters) Architecture using a concrete example: an AWS Lambda behind API Gateway that creates a “package”, enriches it with metadata, and stores it in DynamoDB. It intentionally contains:
• src/bad/smushed.ts: a “everything in one place” anti-example
• src/good/**: the hexagonal rewrite, decomposed into handlers (inbound adapters), services (application/core), repositories (outbound adapters), and domain models
Read the file tree as architecture boundaries
Use the directory structure as your first-pass component list:
Main components to include (split into as many as possible)
When drawing, don’t collapse too early. For this project, explicitly separate at least:
External / Runtime (outside your system)
• API Client (browser / curl / other service)
• AWS API Gateway (HTTP entry)
• AWS Lambda runtime (invokes handler)
• DynamoDB (persistence)
• (Optional but implied) Identity Provider / auth verification mechanism (README mentions Cognito as an example; code has auth.service.ts which likely validates claims/tokens)
Inbound adapter
• Package Handler (AWS Lambda adapter)
File: src/good/handlers/package.lambda.ts
• Translate API Gateway event → domain inputs
• Call application service(s)
• Translate results/errors → HTTP response
Application core (center)
• Package Service (use-case/business logic)
File: src/good/services/package.service.ts
• “Create package” use case
• Adds metadata/TTL/time handling (per README’s “no magic numbers” point)
• Depends on repository + auth service abstractions (even if “interface” is structural typing)
• Auth Service (use-case-supporting domain service)
File: src/good/services/auth.service.ts
• Extract/validate identity context (generic, not Lambda-specific)
Outbound adapter
• Package Repository (DynamoDB adapter)
File: src/good/repositories/package.repository.ts
• CRUD/persistence operations
• Retry/error handling belongs here (per README motivation)
Domain model
• Package model + related types
File: src/good/models/index.ts
Important: show that *all* edges exchange domain types, not AWS SDK types.
Composition / Dependency Injection
• Injector / Wiring (composition root)
README: Sailplane Injector
Even if the wiring isn’t obvious in a single file, represent it as:
• “DI Container / Factory” that builds handler with service + repo + auth dependencies
You want two complementary views:
Static/component view (dependencies)
• package.lambda.ts → package.service.ts
• package.service.ts → auth.service.ts
• package.service.ts → package.repository.ts
• package.repository.ts → DynamoDB (AWS SDK)
• All of the above → models/index.ts for shared domain types
Crucial hexagonal rule to capture visually:
• Adapters depend on core; core is stable.
Dynamic/sequence view (runtime call flow)
For the “Create Package” endpoint:
Return chain back: DynamoDB → repo → service → handler → API Gateway → client
• Where translation happens (event ↔ domain; domain ↔ persistence)
• Where errors are mapped to HTTP responses
• Where DI-created objects are used (constructed once per invocation/container)
This repo is explicitly about these; label them directly:
• Hexagonal / Ports & Adapters: handler + repository are adapters; services are the core.
• DRY & testability: each module has focused tests:
• Handler tests: request/response translation + orchestration
• Service tests: pure business rules
• Repo tests: persistence logic/error behavior
• Auth tests: identity derivation/validation
• No environment leakage: domain models are not AWS-shaped.
Technologies to annotate (only those that matter architecturally)
Small tech badges/labels on components:
• TypeScript / Node.js (implementation language/runtime)
• AWS API Gateway (HTTP front door)
• AWS Lambda (compute/runtime adapter)
• DynamoDB (data store)
• Sailplane Injector (DI / composition)
• Test framework (not visible in README, but *.spec.ts indicates unit testing; label generically as “Unit Tests” if unsure)
Clear labels (use file names to prevent ambiguity)
Example component labels:
• “Inbound Adapter: src/good/handlers/package.lambda.ts”
• “Core Use Case: src/good/services/package.service.ts”
• “Core Service: src/good/services/auth.service.ts”
• “Outbound Adapter: src/good/repositories/package.repository.ts”
• “Domain: src/good/models/index.ts”
• Double-headed only if it’s truly bidirectional (try to avoid; hexagonal aims for one-way dependencies)
• “API Gateway Event” (into handler)
• “Domain Command/DTO: CreatePackageRequest”
• “Domain Model: Package”
• “Persistence Record / PutItem”
• “HTTP Response”