Architecture

Sourcing is built on Raku's powerful metaprogramming capabilities. It uses custom metaclasses, roles, and traits to provide a declarative API for event sourcing.

Component Diagram

┌──────────────────────────────────────────────────────────┐
│                     Sourcing.rakumod                      │
│  (exports: sourcing, traits, EXPORTHOW/DECLARE)          │
└───────────────┬──────────────────────┬───────────────────┘
                │                      │
                ▼                      ▼
    ┌──────────────────┐   ┌──────────────────────────┐
    │  Roles           │   │  Metamodel/              │
    │  - Projection    │   │  - ProjectionHOW         │
    │  - Aggregation   │   │  - AggregationHOW        │
    │  - ProjectionId  │   │  - ProjectionIdContainer │
    │  - ProjectionIdMap│  │  - EventHandlerContainer │
    └──────────────────┘   └──────────────────────────┘
                │
                ▼
    ┌──────────────────────────┐
    │  Sourcing/               │
    │  - Plugin                │
    │  - Plugin::Memory        │
    │  - ProjectionStorage     │
    │  - X::OptimisticLocked   │
    └──────────────────────────┘

Runtime Flow

Command ──► Aggregation ──► emit(event) ──► Plugin (Event Store)
                │                                │
                │ validates                      │ appends to @!events
                │ enforces invariants            │ broadcasts on Supply
                ▼                                ▼
            (state from events)          ProjectionStorage
                                              │
                                        routes events
                                              ▼
                                    ┌─────────┴─────────┐
                                    ↓                   ↓
                              Projection 1        Projection 2
                              (dashboard)         (analytics)

Key Design Decisions

Decision	Rationale
Metaclass-based	Custom HOWs add introspection capabilities and auto-generate methods
Role composition	Functionality is composed through roles for flexibility
Trait-driven	Raku's trait_mod:<is> enables declarative configuration
Supply-based streaming	Raku's Supply provides reactive event distribution
Plugin architecture	Storage backends are pluggable (Memory, future: SQLite, PostgreSQL)

File Structure

lib/
├── Sourcing.rakumod              # Main module, exports, traits
├── Sourcing/
│   ├── Projection.rakumod        # Role for projections
│   ├── Aggregation.rakumod       # Marker role for aggregations
│   ├── ProjectionId.rakumod      # Role for ID attributes
│   ├── ProjectionIdMap.rakumod   # Role for ID mapping
│   ├── ProjectionStorage.rakumod # Event router / registry
│   ├── Plugin.rakumod            # Abstract plugin interface
│   ├── Plugin/
│   │   └── Memory.rakumod        # In-memory implementation
│   └── X/
│       └── OptimisticLocked.rakumod # Exception class
└── Metamodel/
    ├── ProjectionHOW.rakumod     # Metaclass for projections
    ├── AggregationHOW.rakumod    # Metaclass for aggregations
    ├── ProjectionIdContainer.rakumod  # ID introspection
    └── EventHandlerContainer.rakumod  # Event handler introspection

Next Steps

• Dive into Projections — the read model
• Dive into Aggregations — the write model
• Follow the Quick Start Guide