---
auto_generated: true
created: 2026-05-19
manual_updated_at: 2026-05-19
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/barclays
- status/active
- tech/azure-ad
- tech/docker
- tech/fastapi
- tech/gemini
- tech/llamaindex
- tech/postgresql
- tech/python
- tech/rag
- type/project
type: project
---

# Mod Comms Developer Manual

## Architecture Overview

Mod Comms is a FastAPI-based backend application that interacts with a PostgreSQL database and utilizes a multi-agent AI system powered by Google Gemini. The architecture involves:

*   **Backend (FastAPI):** Handles API requests, authentication (Azure AD), and business logic.
*   **Multi-Agent AI System:** Four specialist agents (Legal, Brand, Tone, Channel) analyze assets in parallel, with a Lead Agent synthesizing the final verdict.
*   **Database (PostgreSQL):** Stores campaigns, proofs, user data, audit trails, and reference documents.
*   **File Storage:** Local or cloud-based storage for uploaded proof assets.
*   **Knowledge Base:** Optional integration with LlamaParse for advanced document processing.

### Multi-Agent Flow

```
User Request -> Analysis Orchestrator -> [Legal, Brand, Tone, Channel Agents] -> Lead Agent -> Final Verdict
```

## Tech Stack

*   **Backend:** Python, FastAPI
*   **Database:** PostgreSQL 16
*   **AI Service:** Google Gemini API
*   **Authentication:** Azure AD
*   **ORM/Database Migrations:** SQLAlchemy, Alembic
*   **Containerization:** Docker, Docker Compose
*   **Documentation:** Pptx for presentation generation

## Local Setup

### Prerequisites

*   Python 3.10+
*   Docker and Docker Compose
*   Google Gemini API Key
*   Azure AD Credentials (Tenant ID, Client ID) OR set `DISABLE_AUTH=true` for local dev.

### Steps

1.  **Clone the repository.**
2.  **Configure Environment Variables:**
    *   Copy `.env.example` to `.env` in the `backend/` directory.
    *   Set required variables (see Environment Variables section).
3.  **Start Infrastructure:**
    ```bash
    docker-compose up -d postgres
    ```
4.  **Run Migrations:**
    ```bash
    cd backend
    alembic upgrade head
    ```
5.  **Start Backend:**
    ```bash
    cd backend
    uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
    ```
6.  **Access the App:** Open `http://localhost:8000` in your browser.

## Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `GEMINI_API_KEY` | Google Gemini API Key | | Yes |
| `DISABLE_AUTH` | Bypass Azure AD for dev | `false` | No |
| `AZURE_TENANT_ID` | Azure AD Tenant ID | | Yes (if auth enabled) |
| `AZURE_CLIENT_ID` | Azure AD Client ID | | Yes (if auth enabled) |
| `DATABASE_URL` | PostgreSQL connection string | `postgresql+asyncpg://modcomms:modcomms_dev@localhost:5432/modcomms` | No |
| `REFERENCE_DOCS_PATH` | Path to reference docs for RAG | `../reference_docs` | No |
| `LLAMA_CLOUD_API_KEY` | LlamaParse API Key | | No |
| `MAILGUN_API_URL` | Mailgun API URL | | No |
| `POSTGRES_USER` | Postgres username | `modcomms` | No |
| `POSTGRES_PASSWORD` | Postgres password | `modcomms_dev` | No |
| `POSTGRES_DB` | Postgres database name | `modcomms` | No |
| `POSTGRES_PORT` | Postgres port | `5432` | No |
| `BACKEND_PORT` | Backend port | `8000` | No |

## Key Services & Entry Points

*   **`app.main.py`**: FastAPI application entry point. Initializes services (Gemini, ReferenceDocs, Analysis, KnowledgeBase) on startup.
*   **`app/config.py`**: Settings management via environment variables.
*   **`app/services/gemini_service.py`**: Interface with Google Gemini API.
*   **`app/services/analysis_service.py`**: Orchestrates multi-agent analysis.
*   **`app/services/reference_docs.py`**: Manages RAG context from reference documents.
*   **`app/models/database.py`**: Database session management and initialization.
*   **`backend/alembic/`**: Database migrations.

### Database Models

*   `Agency`, `User`, `Campaign`, `Proof`, `ProofVersion`, `FlaggedItem`, `ResolvedItem`, `ErrorItem`, `DropdownOption`

## API Reference

*   **Base URL:** `http://localhost:8000`
*   **Health Check:** `GET /health`
*   **Authentication:** Azure AD OAuth2 (unless `DISABLE_AUTH=true`)
*   **Endpoints:** See `app/api/router.py`, `app/api/kb_router.py`, `app/api/analysis_router.py` for specific endpoint details.

## Deployment

1.  **Build Docker Images:**
    ```bash
    docker-compose build
    ```
2.  **Set Production Environment Variables:** Ensure all required secrets are set in the production environment.
3.  **Run Docker Compose:**
    ```bash
    docker-compose up -d
    ```
4.  **Verify Health:** Check `http://<host>:8000/health`.

## Known Gotchas

*   **Database Initialization:** The backend starts in a "stateless mode" if the database is not available during startup. Ensure `postgres` service is healthy before `backend` starts (handled by `depends_on` in `docker-compose.yml`).
*   **Gemini API Key:** Must be valid and have sufficient quota.
*   **Azure AD:** If not using `DISABLE_AUTH`, ensure the Azure AD app is correctly configured with redirect URIs.
*   **Reference Docs:** Ensure `REFERENCE_DOCS_PATH` points to valid documents for RAG context.
*   **LlamaParse:** If using the Knowledge Base feature, a valid `LLAMA_CLOUD_API_KEY` is required.
*   **File Storage:** The `file_storage` volume is persistent. Clean up old files manually if needed.

## Related

- [[01 Projects/ac-helper/DEVELOPER_MANUAL]]
- [[01 Projects/modcomms/USER_MANUAL.md]]
- [[01 Projects/ac-tool/DEVELOPER_MANUAL.md]]
- [[01 Projects/ppt-tool/DEVELOPER_MANUAL.md]]