# phunv-abx/fluvius-py architecture

> Architecture diagram of the GitHub repository phunv-abx/fluvius-py, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phunv-abx/fluvius-py
- Repository: https://github.com/phunv-abx/fluvius-py

## Overview

##### Project type & purpose
- This is an open-source Python framework (“Fluvius”) for building domain-driven backend APIs.
- It provides core building blocks (domain model, commands/events, process engine, query handlers) plus adapters (data connectors, webserver, worker, CLI, rule engines).

##### High-level components
A. Core Domain Layer (src/fluvius/domain)
– Defines Aggregates, Entities, Commands, Events, Contexts, Mutations
– Publishes events into a LogStore (memory or SQL)
B. Data Layer (src/fluvius/data)
– Ports: DataConnector, DataDriver, DataManager, DataSchema, Serializer
– Adapters: in-memory, MongoDB, SQLAlchemy, direct SQL
C. Query Layer (src/fluvius/query)
– Read-model handlers, Field definitions, Operators, Context
D. Process/Workflow Engine (src/fluvius/process)
– Routing of commands/events into workflows, status tracking, engine & manager
E. Webserver Adapters (src/fluvius/webserver)
– FastAPI & Sanic blueprints, handlers, sessions, swagger generator
– Pluggable session backends: Redis, MongoDB, memory, memcache, aioredis
F. Worker (src/fluvius/worker)
– Background job client & server, event serialization, tracker integration
G. Data Mapping CLI (src/fluvius/dmap)
– CLI parser & prober, reader/writer registries, fetcher, processor pipeline, typecasting
H. Rule Engines (src/fluvius/rulepy & rulego)
– Decorators, engine for business-rule evaluation
I. Auth & Security (src/fluvius/auth, src/fluvius/casbin)
– Hash utilities, Casbin RBAC integration
J. Supporting modules
– Configuration (conf), Migrations (alembic), Logging, Forms, Helpers

##### Relationships & data flows
1. External client → HTTP API (FastAPI/Sanic)
- Request passes through webserver adapter → routing layer → invokes Domain commands
2. Domain command handling
- Command → Domain.aggregate/mutation → emits Event(s) → persists via Data Layer (logstore or DB)
3. Query side
- Query request → Query handler reads from Data Layer → returns DTO
4. Process/Workflow
- Domain events → Process router → Workflow engine → may emit new commands/events
5. Worker
- Process-engine jobs or scheduled tasks → dispatched to Worker → executes business logic, writes back via Domain/Data
6. Data Mapping CLI
- User runs “dmap” CLI → reads source (CSV, DB, etc) → processes & transforms → writes to target store
7. Rule evaluation
- Domain or Process logic calls Rule Engine → loads rules → applies to data/context
8. Auth & sessions
- Webserver incoming request → Auth layer hashes/validates → Casbin enforces permissions using policies
9. External systems
- Databases (Postgres, Mongo), Cache/Session stores (Redis, memcache), Message broker or queue for Worker (optional)

##### Architectural patterns & principles
- Domain-Driven Design: clear separation of Domain, Application, Infrastructure
- Hexagonal (Ports & Adapters): core logic unaware of framework or DB
- CQRS: separate command (writes/events) from queries (reads)
- Event Sourcing via LogStore interfaces
- Pluggable modules & extensibility points (readers, writers, data drivers, session backends)
- Workflow orchestration embedded in same framework

## Diagram (Mermaid)

```mermaid
graph TB
  subgraph "Clients & CLI"
    Client["External Client"]:::external
    CLI["Data Mapping CLI (dmap)"]:::tool
  end

  subgraph "API Layer"
    API1["FastAPI Adapter"]:::adapter
    API2["Sanic Adapter"]:::adapter
  end

  subgraph "Application Core"
    Domain["Domain (Aggregates, Commands, Events)"]:::core
    Query["Query (Handlers, Fields, Context)"]:::core
    Process["Process Engine"]:::core
    Rules["Rule Engines (rulepy, rulego)"]:::core
    Auth["Auth & Security"]:::core
  end

  subgraph "Infrastructure Adapters"
    Data["Data Layer (Memory, MongoDB, SQLAlchemy, DirectSQL)"]:::adapter
    SessionStore["Session Backends (Redis, MongoDB, Memory, Memcache, Aioredis)"]:::adapter
  end

  subgraph "Worker Runtime"
    Worker["Worker (Client, Server, Serializer, Tracker)"]:::adapter
  end

  subgraph "External Services"
    Postgres[(Postgres)]:::externalService
    MongoDB[(MongoDB)]:::externalService
    Redis[(Redis)]:::externalService
    MQ[(Message Queue)]:::externalService
  end

  %% Flows
  Client -->|"HTTP Request"| API1
  Client -->|"HTTP Request"| API2
  API1 -->|"Invoke Command"| Domain
  API2 -->|"Invoke Command"| Domain
  Domain -->|"emit Event"| Process
  Domain -->|"persist Event"| Data
  Query -->|"Data read"| Data
  Client -->|"Query Request"| Query
  Process -->|"dispatch Job"| Worker
  Worker -->|"Execute Logic"| Domain
  CLI -->|"dmap"| Data
  Domain -->|"rule eval"| Rules
  API2 -->|"session"| SessionStore
  Data -->|"write/read"| Postgres
  Data -->|"write/read"| MongoDB
  SessionStore -->|"store session"| Redis
  Worker -->|"queue job"| MQ

  %% Click Events
  click Domain "https://github.com/phunv-abx/fluvius-py/tree/main/src/fluvius/domain"
  click Data "https://github.com/phunv-abx/fluvius-py/tree/main/src/fluvius/data"
  click Process "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/process/engine.py"
  click Query "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/query/handler.py"
  click API1 "https://github.com/phunv-abx/fluvius-py/tree/main/src/fluvius/webserver/fastapi"
  click API2 "https://github.com/phunv-abx/fluvius-py/tree/main/src/fluvius/webserver/sanic"
  click SessionStore "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/webserver/sanic/session/redis.py"
  click SessionStore "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/webserver/sanic/session/mongodb.py"
  click SessionStore "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/webserver/sanic/session/memory.py"
  click SessionStore "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/webserver/sanic/session/memcache.py"
  click SessionStore "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/webserver/sanic/session/aioredis.py"
  click CLI "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/dmap/cli/parser.py"
  click Worker "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/worker/client.py"
  click Worker "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/worker/worker.py"
  click Worker "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/worker/serializer.py"
  click Worker "https://github.com/phunv-abx/fluvius-py/blob/main/src/fluvius/worker/tracker.py"

  %% Styles
  classDef core fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1
  classDef adapter fill:#C8E6C9,stroke:#2E7D32,color:#2E7D32
  classDef external fill:#FFEBEE,stroke:#C62828,color:#C62828
  classDef externalService fill:#FFE0B2,stroke:#EF6C00,color:#E65100
  classDef tool fill:#E0E0E0,stroke:#424242,color:#424242
```
