Architecture Overview

Fullfinity is a modular business application platform built on modern async Python.

System Architecture

┌─────────────────────────────────────────────────────────────┐
│                         Frontend                             │
│                    (React + Mantine UI)                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       REST API Layer                         │
│                         (FastAPI)                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │ Auto CRUD   │  │ Method Exec │  │ Action/View Builder │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                          ORM Layer                           │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Models    │  │   Fields    │  │    Query Builder    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │    Cache    │  │  Security   │  │      Computed       │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       Database Layer                         │
│  ┌─────────────────────────┐  ┌────────────────────────┐    │
│  │    PostgreSQL (asyncpg) │  │   Valkey/Redis Cache   │    │
│  └─────────────────────────┘  └────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Core Components

1. ORM (`fullfinity/engine/`)

The query-intelligent ORM — designed to eliminate wasted work:

Selective Hydration - Request 5 fields, fetch 5 fields
Smart Computed Fields - Each calculation loads only its specific dependencies
Intelligent Prefetching - Related records batched automatically, no N+1
One Expression Language - Q() syntax works in Python, views, security rules, and client-side
True Async - Native async throughout, not a wrapper
Smart Caching - Query result caching with intelligent invalidation

See ORM Design Philosophy for the full story.

2. Module System (`fullfinity/modules/`)

Each module is a self-contained unit:

modules/
├── core/               # Base module (required)
├── crm/               # CRM functionality
├── invoicing/         # Invoicing & accounting
├── inventory/         # Stock management
└── your_module/       # Your custom modules

3. View System

YAML-based declarative views:

Form Views - Detail/edit forms
List Views - Data tables
Kanban Views - Card-based views
Calendar Views - Timeline views
Search Views - Filters and groupings

4. Security Layer

Role-based access control:

Groups - User permission groups
Model Access - CRUD permissions per model
Record Rules - Row-level security

5. Action Builder

Connects views to data:

Window Actions - Define which views show for a model
Menus - Navigation structure
View Resolution - Inheritance and composition

Request Flow

1. HTTP Request
   ↓
2. FastAPI Router
   ↓
3. Authentication/Authorization Check
   ↓
4. Action Builder (load views, resolve inheritance)
   ↓
5. ORM Query (with caching)
   ↓
6. Security Filters (record rules)
   ↓
7. Serialization
   ↓
8. HTTP Response

Key Design Decisions

Async-First

All database operations are async using asyncpg:

# Non-blocking I/O
users = await User.filter(active=True).all()

YAML Views (Not XML)

Views are defined in YAML for:

Concise, readable authoring
Better tooling support
Easy diffing of layout changes

Semantic Targeting

View inheritance uses semantic targeting:

target:
  field: name   # Not arch[0].content[1]

Automatic API Generation

Every model is reachable through generic, model-name-parameterized endpoints ({class_name} is the model name):

POST /api/create/{class_name} - Create
POST /api/fetch/{class_name}/{id} - Read one
POST /api/query/{class_name} - List/query with filters
PUT /api/update/{class_name}/{record_id} - Update
DELETE /api/delete/{class_name}/{id} - Delete
POST /api/execute/{class_name}/{method_name} - Call a model method

(Bulk variants — bulk-create, bulk-update, bulk-delete — also exist.)

Database Per Tenant

Each tenant has its own PostgreSQL database for:

Data isolation
Independent module installation
Simplified backup/restore

Directory Structure

fullfinity/
├── main.py              # Application entry point
├── engine/              # Core framework / ORM implementation
│   ├── models.py        # Base Model class + metaclass
│   ├── fields.py        # Field type definitions
│   ├── db.py            # Database manager
│   ├── env.py           # Environment context (per-DB model registry)
│   ├── Q.py             # Query objects
│   ├── cache.py         # Cache manager
│   ├── module_registry.py  # Manifest loading + load order
│   └── licensing/       # Enterprise gating
├── modules/             # Application modules
│   ├── core/            # Core module
│   └── ...              # Other modules
└── app/                 # Frontend (React)

Next Steps

Multi-Tenancy - Database isolation
Module System - How modules work