Campaign Brain Documentation¶

Welcome to the Campaign Brain platform documentation. Campaign Brain is a multi-tenant SaaS platform for political campaign management.

Platform Architecture¶

graph TB
    subgraph "Infrastructure Layer"
        INFRA[Infrastructure<br/>cbinfra]
        NGINX[NGINX<br/>Reverse Proxy]
        SSL[SSL/DNS<br/>Let's Encrypt]
        FILES[File Storage<br/>cbfiles + MinIO]
        CDN[CDN<br/>cdn.nominate.ai]
        INTEL[Intel Service<br/>cbintel]
    end

    subgraph "Public Layer"
        PW[Public Website<br/>cbpublic]
        DD[District Data<br/>cbdistricts]
    end

    subgraph "Core Platform"
        TM[Tenant Manager<br/>cbtenant]
        DOCS[Documentation<br/>docs.nominate.ai]

        subgraph "Tenant Instances"
            T1[Tenant 1<br/>cbapp]
            T2[Tenant 2<br/>cbapp]
            T3[Tenant N<br/>cbapp]
        end
    end

    subgraph "Services Layer"
        AI[AI Service<br/>cbai]
        WF[Workflow Engine<br/>cbworkflow]
        ETL[ETL Pipeline<br/>cbetl]
        MOD[Models & Analytics<br/>cbmodels]
        SRV[Survey Platform<br/>cbsurveys]
        RAD[Radio Advertising<br/>cbradio]
    end

    subgraph "Partners"
        P_EMAIL[Email]
        P_P2P[P2P Texting]
        P_CALLS[Live Calls]
        P_ADS[Advertising]
    end

    subgraph "External Users"
        USERS[App Users]
    end

    INFRA --> NGINX
    INFRA --> SSL
    FILES --> CDN
    NGINX --> PW
    NGINX --> TM
    NGINX --> T1
    NGINX --> T2
    PW -->|signup| TM
    DD -->|district data| PW
    TM -->|deploy| T1
    TM -->|deploy| T2
    TM -->|deploy| T3
    T1 -.->|files| FILES
    T2 -.->|files| FILES
    WF -.->|files| FILES
    SRV -.->|files| FILES
    AI -->|chat/embed| T1
    AI -->|chat/embed| T2
    WF -.->|automation| T1
    WF -.->|automation| T2
    WF -.->|outreach| P_EMAIL
    WF -.->|outreach| P_P2P
    WF -.->|outreach| P_CALLS
    WF -.->|outreach| P_ADS
    ETL -->|contact data| TM
    MOD -->|insights| T1
    MOD -->|insights| T2
    RAD -->|media rates| T1
    RAD -->|media rates| T2
    SRV -->|surveys| T1
    SRV -->|surveys| T2
    CDN -->|public files| USERS

Platform Components¶

Component	Repository	Description	Tech Stack
Tenant Manager	cbtenant	Multi-tenant orchestration, deployment, upgrades, List Loader	FastAPI, FastHTML, SQLite
Campaign App	cbapp	Per-tenant campaign management (contacts, events, comms)	FastAPI, DuckDB, HTMX
AI Service	cbai	Unified AI provider access (Claude, Ollama, Mistral)	FastAPI, Anthropic, Ollama
Workflow Engine	cbworkflow	JSON-backed workflow automation for CRM	FastAPI, JSON storage
Districts	cbdistricts	Congressional district data platform (Census, maps)	FastAPI, DuckDB, MapLibre
Models & Analytics	cbmodels	Data analysis, correlations, and segment insights	FastAPI, DuckDB
Radio Advertising	cbradio	AM/FM radio rate card management and ingestion	FastAPI, Airtable
ETL Pipeline	cbetl	Contact data processing (extract, normalize, dedupe)	FastAPI, libpostal
Public Website	cbpublic	Marketing site with district pages and signup	FastHTML, Wikipedia API
Survey Platform	cbsurveys	API-only survey service (YASP)	FastAPI, Pydantic, DuckDB
File Storage	cbfiles	Centralized file storage and CDN delivery	FastAPI, MinIO, DuckDB
Infrastructure	cbinfra	NGINX, systemd, SSL, DNS, deployment scripts	NGINX, systemd, BIND, Certbot
Documentation Hub	cbdocs	Platform documentation (MkDocs)	MkDocs Material, Python
API Mesh	cbmesh	Distributed WebSocket proxy for FastAPI services	Python, FastAPI, WebSockets
Intelligence Service	cbintel	AI-powered web crawling and knowledge synthesis	FastAPI, Playwright, VPN cluster
Executive Publication	cbproject	Interactive MDX publication for stakeholders	Next.js, MDX, Tailwind, Framer Motion
Authentication	cbauth	PIN Gate domain-wide auth for *.nominate.ai	FastAPI, NGINX auth_request
Session Manager	cbos	Claude Code session manager with API and TUI	FastAPI, Textual, GNU Screen

Service Details¶

cbtenant - Tenant Manager¶

The central orchestration system that manages the entire platform.

Functions: Tenant lifecycle (create, deploy, upgrade, delete), service management, port allocation, List Loader
Ports: Frontend 32200, API 32201
Docs: Overview | API | CLAUDE.md

cbapp - Campaign App¶

The core application deployed for each tenant campaign.

Functions: Contact management, event tracking, communications, i360 integration
Database: DuckDB with property graph (DuckPGQ)
Docs: Overview | Features | CLAUDE.md

cbai - AI Service¶

Unified AI provider access with automatic fallback routing.

Providers: Claude (Anthropic), Ollama (local), Mistral (OCR), Unstructured
Endpoints: /api/v1/chat, /api/v1/embed, /api/v1/summarize, /api/v1/ocr
Docs: CLAUDE.md

cbworkflow - Workflow Engine¶

Lightweight workflow automation for CRM contact management.

Features: Contact workflows, template-based automation, event timelines
Nodes: ACTION, DECISION, WAIT, WEBHOOK, END
Docs: Overview | API | CLAUDE.md

cbdistricts - District Data Platform¶

Congressional district data mining and visualization for all 441 U.S. districts.

Data: Census Bureau demographics, TIGER/Line boundaries, ACS profiles
Features: Interactive maps, district comparisons, representative info
Docs: API | CLAUDE.md

cbetl - ETL Pipeline¶

Contact data processing service for political data.

Pipeline: Convert > Analyze > Normalize > Hygiene > Entity Resolution
Features: PID generation (SHA256), address normalization (libpostal), deduplication
Docs: CLAUDE.md

cbpublic - Public Website¶

Marketing website with dynamic district pages.

Features: Marketing funnel, district pages (ia03.nominate.ai), 3-step signup
Data: Wikipedia API for district info, cached 48-72 hours
Docs: Website Plan | CLAUDE.md

cbmodels - Models & Analytics¶

Data analysis engine for discovering patterns in campaign data.

Features: Correlation discovery, outlier detection, segment comparison
Components: CLI model builder, FastAPI analysis server
Port: 32411
Docs: Overview | CLAUDE.md

cbradio - Radio Advertising¶

AM/FM radio rate card and advertising data management.

Features: Rate card ingestion, station data, political advertising rates
Data Source: Airtable exports, PDF rate cards
Port: 32330/32331
Docs: Rate Ingestion | CLAUDE.md

cbsurveys - Survey Platform¶

YASP (Yet Another Survey Platform) - API-only survey service.

Features: Survey creation, question management, response collection
Database: One DuckDB per survey for data isolation
Port: 32340
Domain: surveys.nominate.ai
Docs: Overview | CLAUDE.md

cbfiles - File Storage & CDN¶

Centralized file storage service for all platform modules.

Features: File upload/download, bucket management, signed URLs, CDN delivery
Backend: MinIO object storage with Python SDK
API: files.nominate.ai
CDN: cdn.nominate.ai
Docs: Overview | Developer Guide | CLAUDE.md

cbinfra - Infrastructure¶

Platform infrastructure management and operations.

Features: NGINX reverse proxy, systemd services, SSL certificates, DNS zones
Components: Service templates, deployment scripts, logging tools, runbooks
Docs: Overview | Logging | CLAUDE.md

cbdocs - Documentation Hub¶

Platform documentation and developer resources.

Features: MkDocs Material theme, service documentation, guides, API references
Tech Stack: MkDocs, Python, Material theme
Content: Platform documentation, service guides, architecture diagrams
Docs: Home | Overview

cbmesh - API Mesh¶

Distributed WebSocket proxy network for FastAPI services.

Features: Service discovery via UDP broadcast, API Cards, message routing, Gateway
Components: API Workers, Service Registry, WebSocket Gateway
Use Case: Connect and proxy multiple FastAPI services through a unified mesh
Docs: Overview | Full Guide | CLAUDE.md

cbintel - Intelligence Service¶

Intelligence gathering and knowledge synthesis toolkit with AI-powered web crawling.

Features: AI crawling pipeline, VPN cluster management, vector embeddings, screenshot automation
Packages: ai, net, io, crawl, lazarus, vectl, screenshots, cluster, geo, jobs
Ports: 9003 (intel.nominate.ai), 32203 (network.nominate.ai)
Systemd: cbintel.service
Docs: Overview | Getting Started | API Reference | CLAUDE.md

cbproject - Executive Publication¶

Interactive MDX-based publication for sales, business, and executive stakeholders.

Features: Visual narrative, infographic-style pages, interactive components
Tech Stack: Next.js 14+, MDX, Tailwind CSS, Framer Motion, Lucide Icons
Audience: Political technology decision-makers, campaign executives, investors
Docs: Overview | Full Guide | CLAUDE.md

cbauth - PIN Gate Authentication¶

Domain-wide PIN-based authentication for *.nominate.ai subdomains.

Features: Single PIN grants access to all subdomains, NGINX auth_request integration
Port: 32202
Domain: auth.nominate.ai
Docs: Overview | Full Guide | CLAUDE.md

cbos - Session Manager¶

Claude Code Operating System - session manager for running multiple Claude Code instances.

Features: REST API, TUI interface, WebSocket real-time updates, GNU Screen integration
Port: 32900
Systemd: cbos.service
Use Case: Managing multiple concurrent Claude Code sessions with monitoring and input control
Docs: Overview | MVP Plan | CLAUDE.md

Quick Links¶

Getting Started

Install and configure Campaign Brain in minutes

Installation
Tenant Manager

Deploy and manage multiple campaign instances

Tenant Manager
Architecture

Understand the platform design and database schema

Architecture
List Loader

Import voter data and contact lists

List Loader
Dev Status

Open issues and development progress

Dev Status

Current Versions¶

Component	Version	Status
Tenant Manager (cbtenant)	v1.2.0	Stable
Campaign App (cbapp)	v0.4.81	Stable
Workflow Engine (cbworkflow)	0.1.0	Active
Districts (cbdistricts)	0.1.0	Active
Models & Analytics (cbmodels)	0.1.0	Active
Radio Advertising (cbradio)	0.1.0	Active
AI Service (cbai)	0.1.0	Development
ETL Pipeline (cbetl)	0.1.0	Development
Public Website (cbpublic)	0.1.0	Active
Survey Platform (cbsurveys)	0.1.0	Active
File Storage (cbfiles)	0.1.0	Active
Infrastructure (cbinfra)	0.1.0	Active
Documentation Hub (cbdocs)	v2.0.0	Active
API Mesh (cbmesh)	0.1.0	Development
Intelligence Service (cbintel)	0.2.0	Active
Executive Publication (cbproject)	0.1.0	Development
Authentication (cbauth)	0.1.0	Active
Session Manager (cbos)	0.1.0	Active

See Inventory for complete service details including ports and domains.

Support¶

GitHub Issues: Report bugs or request features
Dev Status: View all open issues
Documentation: You're here!

Last updated: December 31, 2025