# onicagroup/hexagonal-example architecture

> Architecture diagram of the GitHub repository onicagroup/hexagonal-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/onicagroup/hexagonal-example
- Repository: https://github.com/onicagroup/hexagonal-example

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================================================
  %% Diagram 1: Hexagonal (Ports & Adapters) Component View
  %% =========================================================
  subgraph D1["Diagram 1 — Hexagonal Architecture (Ports & Adapters)"]
    direction TB

    subgraph EXT["External / Runtime (Outside System Boundary)"]
      direction TB
      Client["API Client\n(Browser / curl / service)"]:::external
      APIGW["AWS API Gateway\n(HTTP entry)"]:::aws
      LambdaRuntime["AWS Lambda Runtime\n(invokes handler)"]:::aws
      IdP["Identity Provider\n(e.g., Cognito / JWT issuer)"]:::external
      DDB[("DynamoDB\n(Table)")]:::db
    end

    subgraph INB["Inbound Adapter (Delivery)"]
      direction TB
      Handler["Package Lambda Handler\n(Inbound Adapter)"]:::inbound
    end

    subgraph CORE["Application Core (Stable)"]
      direction TB
      Models["Domain Models / Types\n(Package, DTOs, errors)"]:::domain
      PackageSvc["Package Service\n(Create package use case)"]:::core
      AuthSvc["Auth Service\n(Identity derivation/validation)"]:::core
      Injector["DI / Composition Root\n(Sailplane Injector wiring)"]:::di
    end

    subgraph OUTB["Outbound Adapter (Persistence)"]
      direction TB
      Repo["Package Repository\n(DynamoDB adapter)"]:::outbound
    end

    %% --- Runtime call flow (solid) ---
    Client -->|"HTTP request"| APIGW
    APIGW -->|"API Gateway event"| LambdaRuntime
    LambdaRuntime -->|"invoke"| Handler

    %% DI wiring (dashed: construction/wiring)
    Injector -.->|"constructs"| Handler
    Injector -.->|"constructs"| PackageSvc
    Injector -.->|"constructs"| AuthSvc
    Injector -.->|"constructs"| Repo

    %% Handler orchestration (solid)
    Handler -->|"validate/derive identity"| AuthSvc
    Handler -->|"CreatePackageRequest"| PackageSvc

    %% Core to outbound (solid)
    PackageSvc -->|"save(Package)"| Repo
    Repo -->|"PutItem/UpdateItem"| DDB

    %% Core-only dependencies (dotted: compile-time / imports / uses types)
    Handler -.->|"uses types"| Models
    PackageSvc -.->|"uses types"| Models
    AuthSvc -.->|"uses types"| Models
    Repo -.->|"uses types"| Models

    %% Auth external relationship
    AuthSvc -->|"verify token/claims"| IdP

    %% Explicit hexagonal rule (note)
    Rule1["Rule: Core does NOT depend on\nAPI Gateway / Lambda event types / DynamoDB SDK types"]:::note
    Rule1 --- PackageSvc
  end

  %% =========================================================
  %% Anti-example (contrast)
  %% =========================================================
  subgraph BAD["Anti-example (for contrast)"]
    direction TB
    Smushed["Smushed Lambda\n(all concerns in one file)"]:::anti
    Smushed -->|"parses event + auth + business logic + DynamoDB calls\n+ TTL/time + error mapping"| DDB
    APIGW -->|"event"| Smushed
  end

  %% =========================================================
  %% Diagram 2: Deployment / Runtime (AWS-specific)
  %% =========================================================
  subgraph D2["Diagram 2 — Deployment / Runtime (AWS)"]
    direction TB

    Client2["API Client"]:::external
    APIGW2["AWS API Gateway"]:::aws

    subgraph LAMBDAFN["AWS Lambda Function: create-package"]
      direction TB
      Handler2["package.lambda.ts\n(Handler)"]:::inbound
      PackageSvc2["package.service.ts\n(Core use case)"]:::core
      AuthSvc2["auth.service.ts\n(Core service)"]:::core
      Repo2["package.repository.ts\n(Outbound adapter)"]:::outbound
      Models2["models/index.ts\n(Domain types)"]:::domain
    end

    DDB2[("DynamoDB Table")]:::db
    IdP2["Identity Provider\n(Cognito/JWT)"]:::external

    Client2 -->|"HTTP POST /packages"| APIGW2
    APIGW2 -->|"event"| Handler2
    Handler2 -->|"CreatePackageRequest"| PackageSvc2
    Handler2 -->|"identity context"| AuthSvc2
    PackageSvc2 -->|"save(Package)"| Repo2
    Repo2 -->|"PutItem"| DDB2
    AuthSvc2 -->|"verify"| IdP2

    Handler2 -.->|"uses"| Models2
    PackageSvc2 -.->|"uses"| Models2
    AuthSvc2 -.->|"uses"| Models2
    Repo2 -.->|"uses"| Models2
  end

  %% =========================================================
  %% Diagram 3: Sequence — Create Package (dynamic)
  %% =========================================================
  subgraph D3["Diagram 3 — Sequence (Create Package)"]
    direction TB

    subgraph SEQ["Runtime Call Flow (ordered)"]
      direction TB
      S1["1) Client → API Gateway\nHTTP POST /packages"]:::step
      S2["2) API Gateway → Lambda Runtime\nEvent"]:::step
      S3["3) Runtime → Handler\nInvoke package.lambda.ts"]:::step
      S4["4) Handler → AuthService\nValidate/derive identity"]:::step
      S5["5) Handler → PackageService\ncreatePackage(CreatePackageRequest)"]:::step
      S6["6) PackageService → PackageRepository\nsave(Package)"]:::step
      S7["7) Repository → DynamoDB\nPutItem/UpdateItem"]:::step
      S8["8) Return chain\nDynamoDB → Repo → Service → Handler → API Gateway → Client"]:::step

      S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8
    end

    Boundary1["Translation boundary:\nAPI Gateway event ↔ Domain inputs"]:::note
    Boundary2["Translation boundary:\nDomain model ↔ Persistence record"]:::note
    S3 --- Boundary1
    S6 --- Boundary2
  end

  %% =========================================================
  %% Tests & Tooling (outside the hexagon but in repo)
  %% =========================================================
  subgraph SUPPORT["Repo Support: Tests & Tooling"]
    direction TB
    Readme["README\n(Architecture + DI notes)"]:::doc
    Images["Conceptual Diagrams (images/)"]:::doc
    D1Ref["Diagram 1 (concept)"]:::doc
    HandlerSpec["Handler Unit Tests\n(package.lambda.spec.ts)"]:::test
    PkgSvcSpec["Package Service Unit Tests\n(package.service.spec.ts)"]:::test
    AuthSvcSpec["Auth Service Unit Tests\n(auth.service.spec.ts)"]:::test
    RepoSpec["Repository Unit Tests\n(package.repository.spec.ts)"]:::test
    PkgJson["Build/Tooling\npackage.json"]:::tooling
    TSConfig["TypeScript Config\ntsconfig.json"]:::tooling
    TSLint["Lint Config\ntslint.json"]:::tooling

    HandlerSpec -.->|"tests"| Handler
    PkgSvcSpec -.->|"tests"| PackageSvc
    AuthSvcSpec -.->|"tests"| AuthSvc
    RepoSpec -.->|"tests"| Repo

    Readme -.->|"documents"| Injector
    Images -.->|"illustrates"| D1Ref
  end

  %% =========================================================
  %% Click Events (from component_mapping) — paths ONLY
  %% =========================================================
  click Smushed "https://github.com/onicagroup/hexagonal-example/blob/master/src/bad/smushed.ts"
  click Handler "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/handlers/package.lambda.ts"
  click Handler2 "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/handlers/package.lambda.ts"
  click HandlerSpec "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/handlers/package.lambda.spec.ts"

  click PackageSvc "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/services/package.service.ts"
  click PackageSvc2 "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/services/package.service.ts"
  click PkgSvcSpec "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/services/package.service.spec.ts"

  click AuthSvc "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/services/auth.service.ts"
  click AuthSvc2 "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/services/auth.service.ts"
  click AuthSvcSpec "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/services/auth.service.spec.ts"

  click Repo "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/repositories/package.repository.ts"
  click Repo2 "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/repositories/package.repository.ts"
  click RepoSpec "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/repositories/package.repository.spec.ts"

  click Models "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/models/index.ts"
  click Models2 "https://github.com/onicagroup/hexagonal-example/blob/master/src/good/models/index.ts"

  click Readme "https://github.com/onicagroup/hexagonal-example/blob/master/README.md"
  click Images "https://github.com/onicagroup/hexagonal-example/tree/master/images/"
  click PkgJson "https://github.com/onicagroup/hexagonal-example/blob/master/package.json"
  click TSConfig "https://github.com/onicagroup/hexagonal-example/blob/master/tsconfig.json"
  click TSLint "https://github.com/onicagroup/hexagonal-example/blob/master/tslint.json"

  %% =========================================================
  %% Styles (color is critical)
  %% =========================================================
  classDef external fill:#ECEFF1,stroke:#455A64,stroke-width:1px,color:#102027;
  classDef aws fill:#E3F2FD,stroke:#1565C0,stroke-width:1px,color:#0D47A1;
  classDef db fill:#F3E5F5,stroke:#6A1B9A,stroke-width:1px,color:#4A148C;

  classDef inbound fill:#FFEBEE,stroke:#C62828,stroke-width:1px,color:#7F0000;
  classDef outbound fill:#FFF3E0,stroke:#EF6C00,stroke-width:1px,color:#E65100;

  classDef core fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px,color:#1B5E20;
  classDef domain fill:#E1F5FE,stroke:#0277BD,stroke-width:1px,color:#01579B;

  classDef di fill:#FFFDE7,stroke:#F9A825,stroke-width:1px,color:#6D4C41;
  classDef note fill:#FFF8E1,stroke:#FF8F00,stroke-width:1px,color:#5D4037;

  classDef anti fill:#FCE4EC,stroke:#AD1457,stroke-width:1px,color:#880E4F;

  classDef test fill:#F1F8E9,stroke:#558B2F,stroke-width:1px,color:#33691E;
  classDef tooling fill:#E0F7FA,stroke:#00838F,stroke-width:1px,color:#004D40;
  classDef doc fill:#EDE7F6,stroke:#5E35B1,stroke-width:1px,color:#311B92;

  classDef step fill:#FFFFFF,stroke:#37474F,stroke-width:1px,color:#263238;
```
