Intent LogoIntent| Documentation
Source Code

Intent Architecture Reflections

Summary

Intent is built using a architecture that combines several modern software design patterns and approaches. As a multi-tenant, hexagonal backend, it serves as a pragmatic, principled reference implementation for event-sourced CQRS systems:

  1. Domain-Driven Design (DDD): The codebase is organized around the business domain, with clear separation between core domain logic and infrastructure concerns.

  2. Event Sourcing: The system uses events as the source of truth, storing all changes to the application state as a sequence of events.

  3. Command Query Responsibility Segregation (CQRS): Commands (write operations) and queries (read operations) are separated, with different models for writing and reading data.

  4. Temporal Workflow Orchestration: Complex business processes are orchestrated using Temporal, providing durability and reliability for long-running operations.

  5. PostgreSQL Event Store: Events are stored in PostgreSQL, with support for snapshots to optimize performance.

  6. Read Models Projections: Events are projected into read-optimized models to support efficient querying.

  7. Multi-tenancy: The system is designed to support multiple tenants, with tenant isolation at various levels.

  8. Observability: The system includes tracing and monitoring capabilities for operational visibility.

Key Concepts

ConceptDescriptionImplementation
RegistryRegistry for all core conceptsDefined in src/core/registry.ts
AggregateA cluster of domain objects treated as a single unit for data changesDefined in src/core/shared/aggregate.ts
CommandAn intent to change the system stateRepresented by the Command interface in src/core/contracts.ts
Command BusRoutes commands to appropriate handlersImplemented in src/core/command-bus.ts
EventA record of something that happened in the systemRepresented by the Event interface in src/core/contracts.ts
Event BusRoutes events to interested handlersImplemented in src/core/event-bus.ts
Event StorePersists events as the source of truthImplemented in src/infra/pg/pg-event-store.ts
ProjectionUpdates read models based on eventsImplemented in various files under src/core/slices/*/read-models/ and src/core/example-slices/*/read-models/
Saga/ProcessOrchestrates complex business processesDefined by the SagaDefinition interface in src/core/contracts.ts
Temporal ActivitiesDurable operations that can be retriedImplemented in src/infra/temporal/activities/
Temporal WorkflowsOrchestrates activities in a reliable wayImplemented in src/infra/temporal/workflows/
SnapshotPoint-in-time capture of aggregate stateSupported by the event store for performance optimization
Read ModelOptimized representation of data for queryingUpdated by projections based on events
Multi-tenancySupport for multiple isolated customer environmentsImplemented with tenant_id in commands, events, and database tables
ObservabilityMonitoring and tracing capabilitiesImplemented in src/infra/observability/

Architecture Layers

  1. Core (Domain Layer) – src/core/

    • Contains pure business logic: aggregates, commands, events, and sagas
    • No dependency on infrastructure; replay-safe and testable
    • Organized into domain-specific vertical slices in the slices/ directory with example implementations in example-slices/

  2. Infra (Adapter Layer) – src/infra/

    • Adapters for ports: PostgreSQL (event store, projections), Temporal (workflow engine), Supabase (auth)
    • Command/event pumps, observability hooks, and RLS enforcement live here
    • Respects slice boundaries; no core leakage

  3. Tooling Layer – src/tools/

    • Projection drift repair, snapshot verification, RLS linting, and devX CLI helpers
    • Tied into CI for consistency enforcement and automated repair

Further Topics to Explore