1. Concepts

This section contains the fundamental business knowledge, domain model, and architecture decisions.

Contents

• Domain Model - Core entities, relationships, business rules
• Workflows - Business process flows
• Glossary - Terms and definitions
• Architecture Decision Records (ADR) - Why we made certain choices

ADR Index

ID	Decision	Date
ADR-001	Multi-tenancy strategy	2026-01
ADR-002	Authentication strategy	2026-01
ADR-003	Database technology choice	2026-01

See ADR README for full list.

Repository Architecture

The project is split into 4 repositories:

saas-backend/     → FastAPI + SQLModel + Alembic + PostgreSQL
saas-frontend/    → Flet (Python) - web, mobile, desktop
saas-shared/      → Pydantic schemas (pure, no ORM dependencies)
saas-docs/        → MkDocs + Material theme

The Golden Rule

Repo	Contains	Must NOT contain
saas-shared	Pydantic schemas (API contracts)	SQLAlchemy, ORM models, FastAPI routes
saas-backend	SQLModel models, Alembic migrations	Pydantic schemas (those go in saas-shared)
saas-frontend	Flet UI, consumes saas-shared schemas	Direct database access, ORM models

Forbidden: - saas-backend MUST NOT have Pydantic schemas - saas-shared MUST NOT have SQLAlchemy or FastAPI - saas-frontend MUST NOT have direct database access

System Architecture

graph TD
    subgraph "Frontend (Flet)"
        FE[saas-frontend]
    end

    subgraph "Backend (FastAPI)"
        API[API Routes]
        UC[Use Cases]
        DOM[Domain Entities]
        REPO[Repositories]
        API --> UC --> DOM
        UC --> REPO
    end

    subgraph "Shared"
        SH[saas-shared<br/>Pydantic Schemas]
    end

    subgraph "External"
        PG[(PostgreSQL)]
        ADB[AeroDataBox]
        WAS[WhatsApp Cloud]
        GCP[Cloud Storage]
    end

    FE -->|httpx| API
    API -->|imports| SH
    REPO -->|SQLModel| PG
    UC -->|webhook| ADB
    UC -->|notify| WAS
    UC -->|upload| GCP