Skip to content

Commit 5eb36ad

Browse files
NinjaRocksNinjaRocks
committed
- Update documentation
1 parent 1c2173b commit 5eb36ad

13 files changed

+3569
-388
lines changed

‎docs/Architecture/01-Architecture-Overview.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# SourceFlow.Net - Architecture Overview
2+
3+
## Introduction
4+
SourceFlow.Net is an event-driven architecture framework implementing Command Query Responsibility Segregation (CQRS) and Event Sourcing patterns. The system separates command processing from event handling, enabling scalable and maintainable domain-driven design.
5+
6+
## Core Architectural Patterns
7+
8+
### 1. CQRS (Command Query Responsibility Segregation)
9+
- **Commands**: Modify state through CommandBus
10+
- **Queries**: Read from materialized views (ViewModels)
11+
- Clear separation between write and read models
12+
13+
### 2. Event Sourcing
14+
- Commands are persisted in CommandStore
15+
- Events represent state changes
16+
- Event replay capability for reconstructing state
17+
18+
### 3. Saga Pattern
19+
- Long-running business processes
20+
- Coordinate multiple commands across aggregates
21+
- Handle complex workflows
22+
23+
## High-Level Component Architecture
24+
25+
```
26+
┌─────────────────────────────────────────────────────────────┐
27+
│ Client Application │
28+
└───────────────────┬─────────────────────────────┬────────────┘
29+
│ │
30+
▼ ▼
31+
┌──────────────────┐ ┌──────────────────┐
32+
│ ICommandBus │ │ IEventQueue │
33+
│ (Publish) │ │ (Enqueue) │
34+
└────────┬─────────┘ └────────┬─────────┘
35+
│ │
36+
▼ ▼
37+
┌──────────────────────┐ ┌──────────────────────┐
38+
│ ICommandDispatcher[] │ │ IEventDispatcher[] │
39+
└──────────┬───────────┘ └──────────┬───────────┘
40+
│ │
41+
▼ │
42+
┌──────────────────────┐ │
43+
│ ICommandSubscriber[] │ │
44+
│ - CommandSubscriber│ │
45+
│ (routes to Sagas)│ │
46+
└──────────┬───────────┘ │
47+
│ │
48+
▼ ▼
49+
┌───────────────┐ ┌─────────────────────┐
50+
│ ISaga[] │ │ IEventSubscriber[] │
51+
│ (Handles │ │ - Aggregate. │
52+
│ Commands) │ │ EventSubscriber │
53+
└───────┬───────┘ │ - Projections. │
54+
│ │ EventSubscriber │
55+
│ Publishes └──────────┬──────────┘
56+
│ Events │
57+
│ │
58+
▼ ▼
59+
┌───────────────┐ ┌─────────────────────┐
60+
│ IEventQueue │ │ IAggregate[] │
61+
│ │ │ IView[] │
62+
└───────────────┘ │ (Subscribe/Project)│
63+
└─────────────────────┘
64+
```
65+
66+
## Key Components
67+
68+
### Command Processing Path
69+
1. **ICommandBus** - Entry point for command publishing
70+
2. **CommandBus** - Manages command persistence and dispatching
71+
3. **ICommandDispatcher** - Routes commands to subscribers
72+
4. **CommandDispatcher** - Dispatches to all registered ICommandSubscriber instances
73+
5. **ICommandSubscriber** - Receives dispatched commands
74+
6. **CommandSubscriber** - Routes commands to appropriate Sagas
75+
7. **ISaga** - Handles commands and produces events
76+
77+
### Event Processing Path
78+
1. **IEventQueue** - Entry point for event publishing
79+
2. **EventQueue** - Manages event distribution
80+
3. **IEventDispatcher** - Routes events to subscribers
81+
4. **EventDispatcher** - Dispatches to all registered IEventSubscriber instances
82+
5. **IEventSubscriber** - Receives dispatched events
83+
- **Aggregate.EventSubscriber** - Routes to Aggregates implementing ISubscribes<TEvent>
84+
- **Projections.EventSubscriber** - Routes to Views implementing IProjectOn<TEvent>
85+
86+
## Storage Abstractions
87+
88+
### Command Storage
89+
- **ICommandStore** - Interface for command persistence
90+
- **ICommandStoreAdapter** - Scoped adapter wrapping ICommandStore
91+
- Stores commands with sequence numbers for replay
92+
93+
### Entity Storage (Aggregates)
94+
- **IEntityStore** - Interface for entity persistence
95+
- **IEntityStoreAdapter** - Scoped adapter wrapping IEntityStore
96+
- Stores aggregate state
97+
98+
### ViewModel Storage (Projections)
99+
- **IViewModelStore** - Interface for read model persistence
100+
- **IViewModelStoreAdapter** - Scoped adapter wrapping IViewModelStore
101+
- Stores materialized views for queries
102+
103+
## Service Lifetimes
104+
105+
### Singleton Services
106+
- **IEventQueue** - Thread-safe event distribution
107+
- **IEventDispatcher** - Stateless event routing
108+
- **IEventSubscriber** (both implementations) - Stateless subscription management
109+
- **IDomainTelemetryService** - Observability and tracing
110+
111+
### Scoped Services
112+
- **ICommandBus** - Per-request command handling
113+
- **ICommandDispatcher** - Per-request command routing
114+
- **ICommandSubscriber** - Per-request subscription handling
115+
- **ICommandPublisher** - Per-request command publishing
116+
- **Store Adapters** (ICommandStoreAdapter, IEntityStoreAdapter, IViewModelStoreAdapter)
117+
118+
### Configurable Lifetime (Default: Singleton)
119+
- **ISaga** implementations
120+
- **IAggregate** implementations
121+
- **IView** implementations
122+
123+
## Dependency Injection Registration
124+
125+
Components are registered using the `UseSourceFlow()` extension method:
126+
127+
```csharp
128+
services.UseSourceFlow(ServiceLifetime.Singleton, assemblies);
129+
```
130+
131+
Key registration points (from IocExtensions.cs:33-98):
132+
- Stores and adapters auto-discovered from assemblies
133+
- Factories registered for aggregate creation
134+
- Lazy<ICommandPublisher> to break circular dependencies
135+
- Event/Command subscribers registered as Singleton/Scoped respectively
136+
137+
## Observability and Telemetry
138+
139+
The framework includes built-in OpenTelemetry support:
140+
- **IDomainTelemetryService** - Provides distributed tracing
141+
- Traces command dispatching, event publishing, and replay operations
142+
- Tags include: command/event type, entity IDs, sequence numbers, subscriber counts
143+
144+
Trace operations:
145+
- `sourceflow.commandbus.dispatch`
146+
- `sourceflow.commandbus.replay`
147+
- `sourceflow.commanddispatcher.send`
148+
- `sourceflow.eventqueue.enqueue`
149+
- `sourceflow.eventdispatcher.dispatch`
150+
151+
## Performance Optimizations
152+
153+
### TaskBufferPool
154+
- ArrayPool-based task collection optimization
155+
- Used in CommandDispatcher and EventDispatcher
156+
- Reduces allocations for parallel subscriber execution
157+
158+
## Key Design Principles
159+
160+
1. **Separation of Concerns**: Commands, Events, Aggregates, Sagas, and Views are distinct
161+
2. **Interface-based Design**: All major components use interfaces for extensibility
162+
3. **Dependency Inversion**: Components depend on abstractions, not implementations
163+
4. **Single Responsibility**: Each component has a focused purpose
164+
5. **Open/Closed Principle**: Extensible through new implementations without modifying core
165+
166+
## Message Metadata
167+
168+
All commands and events implement IMetadata:
169+
- **SequenceNo**: Order of command/event
170+
- **IsReplay**: Flag indicating replay vs. new command/event
171+
- Used for event sourcing and replay scenarios
172+
173+
## Next Steps for Cloud Extension
174+
175+
The architecture's interface-based design makes it suitable for cloud extension:
176+
- New ICommandDispatcher implementation for AWS SQS
177+
- New IEventDispatcher implementation for AWS SNS
178+
- Selective routing based on command/event type
179+
- Maintain existing local processing alongside cloud dispatch

0 commit comments

Comments
 (0)