Skip to main content

What is the Framework?

info

Fluvius Framework is a Python library for building domain-driven API & MCP backends with CQRS, event sourcing, and modern architecture patterns.

Overview​

Fluvius Framework is a comprehensive backend framework designed to help developers build scalable, maintainable applications using proven architectural patterns. It combines the power of Domain-Driven Design (DDD), Command Query Responsibility Segregation (CQRS), and Event Sourcing to create robust, event-driven systems.

Core Philosophy​

Fluvius Framework is built on the principle that business logic should be the heart of your application. Instead of focusing on infrastructure concerns, Fluvius helps you:

  • Model your domain using DDD patterns
  • Separate concerns with CQRS
  • Track changes with event sourcing
  • Scale independently with modular architecture

What Makes Fluvius Different?​

1. Domain-First Approach​

Unlike traditional frameworks that start with database models, Fluvius starts with your business domain. You define aggregates that encapsulate business logic, and the framework handles persistence, events, and state management.

2. Built-in Event Sourcing​

Every state change in Fluvius generates an immutable event. This provides:

  • Complete audit trail
  • Time travel capabilities
  • Event replay for debugging
  • Event-driven integrations

3. CQRS by Default​

Commands and queries are separated from the start:

  • Commands modify state through aggregates
  • Queries read from optimized state stores
  • Independent scaling of read and write paths

4. Modern Python Stack​

Built on modern Python technologies:

  • FastAPI for REST APIs
  • Async/await throughout
  • Type hints for better IDE support
  • Pydantic for validation

5. Multiple Data Backends​

Support for various databases:

  • PostgreSQL
  • MongoDB
  • SQLite
  • Extensible for other backends

Architecture at a Glance​

┌─────────────────────────────────────────┐
│         FastAPI / REST API              │
├─────────────────────────────────────────┤
│         Domain Layer                    │
│  ┌──────────┐  ┌──────────┐           │
│  │Aggregates│  │ Commands │           │
│  └──────────┘  └──────────┘           │
├─────────────────────────────────────────┤
│         Event Store                     │
│  ┌──────────┐  ┌──────────┐           │
│  │  Events  │  │  State   │           │
│  └──────────┘  └──────────┘           │
├─────────────────────────────────────────┤
│         Data Layer                      │
│  PostgreSQL | MongoDB | SQLite         │
└─────────────────────────────────────────┘

Key Components​

Domain Module​

The core of Fluvius, providing aggregates, commands, events, and state management.

FastAPI Module​

REST API integration with automatic endpoint generation from domains.

Data Module​

Database abstraction layer supporting multiple backends.

Worker Module​

Background job processing with ARQ integration.

Query Module​

Flexible querying with filtering, sorting, and pagination.

Media Module​

File upload and storage management.

Casbin Module​

Policy-based authorization and access control.

When to Use Fluvius​

Fluvius is ideal for:

  • Complex business domains with rich business logic
  • Event-driven systems requiring audit trails
  • Microservices needing clear boundaries
  • Applications requiring high scalability
  • Systems with complex authorization requirements

Next Steps​