Clean Architecture with DDD

Modern backend platform built with Domain-Driven Design, Event-Driven Architecture, and Clean Code principles.

---

Architecture Principles

Core DDD Primitives (pkg/)

• aggregate/ - Base Aggregate pattern for domain entities
• valueobject/ - Immutable value objects (Email, Phone, Address, Money, etc.)
• saga/ - Saga pattern for distributed transactions
• uuidv7/ - Time-ordered UUID v7 generation
• logger/ - Structured logging with context
• migration/ - Database migration management
• jsonb/ - PostgreSQL JSONB utilities

Infrastructure (internal/infrastructure/)

• config/ - YAML configuration management
• database/ - PostgreSQL connection, transactions, context management

Contexts Structure (internal/contexts/)

All bounded contexts following DDD principles:

• identity/ - User & Contact aggregates ( In Progress)
• customer-mgmt/ - Customer, Company, Deal, Interaction, Analytics ( All Production)
• order-mgmt/ - Order, OrderItem, Fulfillment ( Planned)
• billing/ - Invoice, Payment, Subscription ( Planned)
• warehouse/ - Inventory management ( Planned)

Migrations (migrations/)

• core/ - Core infrastructure (UUID v7, Users, Auth, RBAC, Reference data)
• identity/ - Identity context migrations

Testing (test/)

• integration/ - Integration test helpers and setup

---

Current Architecture

Bounded Contexts Structure

promenade/
 cmd/
    api/                    #  HTTP server entry point
    migrate/                #  Migration CLI tool
 internal/
    contexts/               #  DDD Bounded Contexts
       identity/          #  User & Contact (in progress)
          user/          #    User aggregate
          contact/       #    Contact aggregate
       customer-mgmt/     #  Customer, Company, Deal
       order-mgmt/        #  Order, OrderItem
       billing/           #  Invoice, Payment
       warehouse/         #  Inventory
    infrastructure/         #  Cross-cutting
        config/            #    Configuration
        database/          #    DB & Transactions
 pkg/                        #  DDD Primitives
    aggregate/             #    Base Aggregate
    valueobject/           #    Value Objects
    saga/                  #    Saga Pattern
    uuidv7/               #    UUID v7
    logger/               #    Logging
    migration/            #    Migrations
    jsonb/                #    JSONB utils
 migrations/                 #  Context Migrations
    core/                 #    Core infrastructure
    identity/             #    Identity context
 test/                       #  Testing
    integration/          #    Integration helpers
 config/                     #  Configuration
    app.postgres-dev.yaml
    app.postgres-test.yaml
    app.postgres-prod.yaml
    app.sqlite-dev.yaml
    app.sqlite-test.yaml
    app.sqlite-prod.yaml
 docs/                       #  Clean DDD docs (to be written)
 README.md                   #  New DDD-focused README

---

Production-Ready Features

• 420+ Tests: Unit (in-place), Smoke (mock-based), Integration (real DB) with 90%+ coverage
• Event Bus: Memory (377K events/sec) and Redis (distributed) adapters
• JWT + RBAC: 5 system roles, 29+ permissions, token revocation
• Health Checks: 4 endpoints monitoring all dependencies
• Rate Limiting: IP-based protection (Login 5/min, Register 3/min)
• Caching Layer: Redis-based with resource-specific TTL
• Docker Support: Compose files for dev/test/prod environments

Status: Production-ready
Version: 1.0.0
Last Updated: December 30, 2025