Architecture Overview¶

Campaign Brain is a multi-tenant SaaS platform for political campaign management.

System Architecture¶

graph TB
    subgraph "Infrastructure"
        NGINX[Nginx Reverse Proxy]
        SYSTEMD[Systemd Services]
    end

    subgraph "Tenant Manager"
        TM_UI[Frontend<br/>:32200]
        TM_API[API<br/>:32201]
        TM_DB[(SQLite<br/>manager.db)]
    end

    subgraph "Tenant: mi20"
        MI_UI[Frontend<br/>:32310]
        MI_API[API<br/>:32311]
        MI_DB[(DuckDB<br/>pocket.db)]
    end

    subgraph "Tenant: ky04"
        KY_UI[Frontend<br/>:32320]
        KY_API[API<br/>:32321]
        KY_DB[(DuckDB<br/>pocket.db)]
    end

    NGINX --> TM_UI
    NGINX --> MI_UI
    NGINX --> KY_UI

    TM_UI --> TM_API
    TM_API --> TM_DB

    MI_UI --> MI_API
    MI_API --> MI_DB

    KY_UI --> KY_API
    KY_API --> KY_DB

    SYSTEMD --> MI_UI
    SYSTEMD --> MI_API
    SYSTEMD --> KY_UI
    SYSTEMD --> KY_API

Components¶

Tenant Manager (cbtenant)¶

The central orchestration system that:

Creates and configures new tenant instances
Manages tenant lifecycle (deploy, upgrade, stop, delete)
Handles port allocation and service management
Provides a dashboard for administrators

Technology Stack:

FastAPI (REST API)
FastHTML (Dashboard UI)
SQLite (Metadata storage)
Systemd (Service management)

Campaign App (cbapp)¶

The core application deployed for each tenant:

Audience management (contacts, voters)
Event tracking
Communication logging
i360 voter data integration
Segment management

Technology Stack:

FastAPI (REST API)
FastHTML (Web UI)
DuckDB (Data storage with vector search)
HTMX (Dynamic UI updates)

Workflow Engine (cbworkflow)¶

Automation and workflow processing:

Scheduled tasks
Event-driven workflows
Integrations with external services

Data Flow¶

sequenceDiagram
    participant Admin
    participant TM as Tenant Manager
    participant GH as GitHub
    participant Tenant as Tenant App

    Admin->>TM: Create Tenant
    TM->>GH: Clone cbapp
    TM->>TM: Allocate Ports
    TM->>TM: Create Services
    TM->>Tenant: Start Services

    Admin->>TM: Upgrade Tenant
    TM->>Tenant: Stop Services
    TM->>GH: Git Pull (version tag)
    TM->>Tenant: Run Migrations
    TM->>Tenant: Start Services

Directory Structure¶

/home/bisenbek/projects/nominate/
├── cbtenant/           # Tenant Manager
│   ├── api/           # FastAPI backend
│   ├── app/           # FastHTML frontend
│   ├── db/            # Database files
│   └── scripts/       # Utility scripts
├── cbapp/             # Source repository
├── testsite/          # Test tenant
├── mi20-clevenger/    # Production tenant
└── ky04/              # Production tenant