How phunv-abx/fluvius-py works
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