Skip to main content

Architecture Diagram

info

Understanding the overall architecture helps you build better applications with Fluvius Framework.

High-Level Architecture​

┌─────────────────────────────────────────────────────────────┐
│                      Client Layer                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Web App    │  │  Mobile App  │  │  API Client  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    API Layer (FastAPI)                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ REST Endpoints│  │  WebSockets  │  │  Middleware  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Domain Layer                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │   Domains    │  │  Aggregates   │  │   Commands   │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │    Events    │  │ State Manager │  │  Processors  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                            │
                ┌───────────┴───────────┐
                ▼                       ▼
┌──────────────────────────┐  ┌──────────────────────────┐
│      Event Store         │  │     State Store          │
│  ┌────────────────────┐  │  │  ┌────────────────────┐  │
│  │  Event Log         │  │  │  │  Current State     │  │
│  │  (Immutable)       │  │  │  │  (Read-Optimized)  │  │
│  └────────────────────┘  │  │  └────────────────────┘  │
└──────────────────────────┘  └──────────────────────────┘
                │                       │
                └───────────┬───────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Data Layer                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │  PostgreSQL  │  │   MongoDB    │  │   SQLite     │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘

Component Flow​

Command Flow​

Client Request
    │
    ▼
FastAPI Endpoint
    │
    ▼
Domain.create_command()
    │
    ▼
Command Processor
    │
    ▼
Aggregate Action
    │
    ├──► Business Logic
    │
    ├──► State Update
    │
    └──► Event Generation
            │
            ├──► Event Store (Write)
            │
            └──► State Store (Update)
                    │
                    └──► Response to Client

Query Flow​

Client Request
    │
    ▼
FastAPI Endpoint
    │
    ▼
State Manager
    │
    ├──► Query Builder
    │
    ├──► State Store (Read)
    │
    └──► Response to Client

Layered Architecture​

1. Presentation Layer​

Components:

  • FastAPI application
  • REST endpoints
  • WebSocket handlers
  • Middleware

Responsibilities:

  • Request/response handling
  • Authentication
  • Input validation
  • Error handling

2. Domain Layer​

Components:

  • Domains
  • Aggregates
  • Commands
  • Events
  • State Manager

Responsibilities:

  • Business logic
  • State management
  • Event generation
  • Command processing

3. Infrastructure Layer​

Components:

  • Event Store
  • State Store
  • Database drivers
  • Message queues
  • File storage

Responsibilities:

  • Data persistence
  • Event storage
  • External integrations
  • Infrastructure concerns

Module Architecture​

fluvius/
├── domain/          # Core domain logic
│   ├── aggregate.py
│   ├── command.py
│   ├── event.py
│   └── state.py
├── fastapi/         # FastAPI integration
│   ├── app.py
│   └── endpoints.py
├── data/            # Data layer
│   ├── driver.py
│   └── models.py
├── worker/          # Background workers
│   └── tasks.py
├── query/           # Query builder
│   └── builder.py
├── media/           # Media management
│   └── manager.py
└── casbin/          # Authorization
    └── enforcer.py

Data Flow​

Write Path (Command)​

  1. Client sends HTTP POST/PUT/DELETE
  2. FastAPI validates request
  3. Domain creates command
  4. Command Processor routes to aggregate
  5. Aggregate executes business logic
  6. Event is generated
  7. Event Store persists event
  8. State Store updates current state
  9. Response returned to client

Read Path (Query)​

  1. Client sends HTTP GET
  2. FastAPI validates request
  3. State Manager queries state store
  4. State Store returns current state
  5. Response returned to client

Event-Driven Architecture​

Aggregate Action
    │
    └──► Event Generated
            │
            ├──► Event Store
            │
            ├──► State Store Update
            │
            ├──► Event Handlers
            │       │
            │       ├──► Notification Service
            │       ├──► Analytics Service
            │       └──► External Systems
            │
            └──► Event Stream
                    │
                    └──► Event Consumers

Scalability Architecture​

Horizontal Scaling​

                    Load Balancer
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
    FastAPI 1        FastAPI 2        FastAPI 3
        │                 │                 │
        └─────────────────┼─────────────────┘
                          │
                    Shared Database
                    (PostgreSQL/MongoDB)

CQRS Scaling​

Write Instances (Commands)
        │
        └──► Event Store
                │
                ├──► Event Replication
                │
                └──► Read Replicas (Queries)
                        │
                        └──► State Store Replicas

Security Architecture​

Client Request
    │
    ▼
Authentication Middleware
    │
    ▼
Authorization (Casbin)
    │
    ├──► Policy Check
    │
    ├──► Resource Check
    │
    └──► Domain Access
            │
            └──► Aggregate Action

Deployment Architecture​

┌─────────────────────────────────────┐
│         Application Container        │
│  ┌───────────────────────────────┐   │
│  │      FastAPI Application      │   │
│  │  ┌─────────┐  ┌───────────┐  │   │
│  │  │ Domains │  │  Workers  │  │   │
│  │  └─────────┘  └───────────┘  │   │
│  └───────────────────────────────┘   │
└─────────────────────────────────────┘
            │
    ┌───────┼───────┐
    │       │       │
┌───▼───┐ ┌─▼───┐ ┌─▼───┐
│  DB   │ │Redis│ │ S3  │
└───────┘ └─────┘ └─────┘

Next Steps​