modcomms/README.md

# Mod Comms

An AI-powered proof review tool for Barclays marketing materials. Mod Comms uses a multi-agent AI system to analyze uploaded marketing assets for legal compliance, brand adherence, tone of voice, and channel suitability.

## Features

- **Multi-Agent Analysis** - Four specialist AI agents analyze proofs in parallel, with a lead agent synthesizing the final verdict
- **Real-Time Feedback** - WebSocket streaming provides live progress updates during analysis
- **Campaign Management** - Organize proofs by campaign with full version history
- **WIP Reviewer** - Get early-stage creative feedback on work-in-progress assets
- **Analytics Dashboard** - Track compliance metrics, status breakdowns, and trends
- **Auditing** - Full audit trail for flagged issues and resolutions
- **PDF Export** - Generate professional reports of analysis results

## Architecture

### Multi-Agent System

```
┌─────────────────────────────────────────────────────────────┐
│                    Analysis Orchestrator                     │
│                                                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐       │
│  │ Legal Agent  │  │ Brand Agent  │  │  Tone Agent  │       │
│  │ Compliance   │  │ Visual ID    │  │ Voice/Clarity│       │
│  └──────────────┘  └──────────────┘  └──────────────┘       │
│                                                             │
│  ┌──────────────┐  ┌──────────────────────────────────┐     │
│  │Channel Agent │  │          Lead Agent              │     │
│  │Platform Specs│  │   Synthesizes Final Verdict      │     │
│  └──────────────┘  └──────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘
```

Each agent returns a RAG status (Red/Amber/Green) with detailed feedback:

| Agent | Responsibility |
|-------|----------------|
| **Legal** | Advertising standards, disclaimers, financial promotion detection |
| **Brand** | Logo usage, color palette, typography, design principles |
| **Tone** | Copy clarity, brand voice, grammar, personality alignment |
| **Channel** | Platform-specific specs, accessibility, technical requirements |
| **Lead** | Synthesizes all feedback and determines overall pass/fail status |

### Tech Stack

**Frontend**
- React 19 with TypeScript
- Vite for build tooling
- TailwindCSS for styling
- jsPDF for report generation

**Backend**
- FastAPI (Python)
- WebSocket for real-time communication
- Google Gemini 2.5 Flash for AI analysis
- PostgreSQL with SQLAlchemy async + asyncpg
- Alembic for database migrations
- Pydantic for data validation

## Project Structure

```
barclays_modcomms/
├── frontend/                    # React web application
│   ├── components/              # UI components
│   ├── services/                # API integrations
│   ├── App.tsx                  # Main app with routing
│   └── types.ts                 # TypeScript definitions
│
├── backend/                     # FastAPI server
│   ├── app/
│   │   ├── agents/              # AI agent implementations
│   │   ├── api/                 # REST endpoints
│   │   ├── models/              # SQLAlchemy ORM and Pydantic schemas
│   │   ├── repositories/        # Data access layer
│   │   ├── services/            # Gemini API, analysis orchestration
│   │   ├── websocket/           # Real-time communication
│   │   └── main.py              # FastAPI entry point
│   ├── alembic/                 # Database migrations
│   └── requirements.txt
│
├── reference_docs/              # Brand & channel guidelines
│   ├── brand/                   # Barclays brand guidelines
│   └── channel/                 # Digital channel specifications
│
├── specs/                       # Product requirements
└── test_files/                  # Sample assets for testing
```

## Getting Started

### Prerequisites

- Node.js 18+
- Python 3.8+
- Google Gemini API key

### Backend Setup

```bash
cd backend

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY

# Start server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

### Frontend Setup

```bash
cd frontend

# Install dependencies
npm install

# Configure environment
cp .env.example .env.local  # or create manually
# Add to .env.local:
#   GEMINI_API_KEY=your_key
#   VITE_BACKEND_WS_URL=ws://localhost:8000/ws/analyze
#   VITE_BACKEND_URL=http://localhost:8000

# Start development server
npm run dev
```

The application will be available at `http://localhost:3000`.

## Environment Variables

### Backend (`backend/.env`)

| Variable | Description | Default |
|----------|-------------|---------|
| `GEMINI_API_KEY` | Google Gemini API key | Required |
| `DATABASE_URL` | PostgreSQL connection string | Required |
| `AZURE_TENANT_ID` | Azure AD tenant ID | Required for auth |
| `AZURE_CLIENT_ID` | Azure AD client ID | Required for auth |
| `DISABLE_AUTH` | Disable auth for local dev | `false` |
| `CORS_ORIGINS` | Allowed CORS origins | `http://localhost:3000` |
| `HOST` | Server host | `0.0.0.0` |
| `PORT` | Server port | `8000` |
| `REFERENCE_DOCS_PATH` | Path to reference docs | `../reference_docs` |

### Frontend (`frontend/.env.local`)

| Variable | Description |
|----------|-------------|
| `GEMINI_API_KEY` | Google Gemini API key |
| `VITE_BACKEND_WS_URL` | WebSocket URL for analysis |
| `VITE_BACKEND_URL` | Backend REST API URL |

## Usage

### Analyzing a Proof

1. Log in to the application
2. Navigate to **Campaigns** and select or create a campaign
3. Upload a marketing asset (image or PDF)
4. Watch the real-time analysis progress as each agent processes the proof
5. Review the feedback report with RAG status for each agent
6. Flag any issues that need attention or mark items as resolved

### Understanding RAG Status

- **Green** - Compliant, no issues found
- **Amber** - Minor issues that should be addressed
- **Red** - Critical issues that must be fixed before approval

### Overall Status Logic

| Status | Condition |
|--------|-----------|
| **Passed** | All agents Green, or minor Amber issues |
| **Failed** | Any agent returns Red |
| **Requires Manual Legal Review** | Financial promotion detected |
| **Analysis Error** | Processing error occurred |

## API Reference

### WebSocket Endpoint

**`/ws/analyze`** - Real-time proof analysis

**Request:**
```json
{
  "type": "analyze",
  "file_data": "<base64-encoded-file>",
  "file_type": "image/png",
  "is_wip": false
}
```

**Response Messages:**
```json
{ "type": "agent_started", "agent_name": "Brand Agent" }
{ "type": "agent_completed", "agent_name": "Brand Agent", "review": {...} }
{ "type": "summary" }
{ "type": "complete", "result": {...} }
```

### REST Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/health` | GET | Health check |
| `/info` | GET | Backend info and reference doc summary |

## Development

### Build for Production

```bash
# Frontend
cd frontend
npm run build
npm run preview  # Preview production build

# Backend
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000
```

### Project Commands

```bash
# Frontend
npm run dev       # Start dev server
npm run build     # Production build
npm run preview   # Preview build

# Backend
uvicorn app.main:app --reload  # Dev server with hot reload
```

### Database Migrations

```bash
cd backend

# Run all pending migrations
alembic upgrade head

# Create a new migration after model changes
alembic revision --autogenerate -m "description of changes"

# Downgrade one revision
alembic downgrade -1
```

## Reference Documentation

The `reference_docs/` directory contains brand and channel guidelines used by the AI agents:

**Brand Guidelines:**
- Barclaycard core principles
- Barclays tone of voice
- Barclays expression core principles
- Brand architecture guidelines
- Brand design language principles

**Channel Guidelines:**
- Barclaycard digital guidelines
- Digital guidelines
- Social media guidelines

## User Roles

| Role | Access |
|------|--------|
| **Admin** | Full access to all campaigns, Settings, Analytics, Auditing |
| **Basic User** | Limited to own agency's campaigns |

## Data Persistence

### Backend (PostgreSQL)

Primary data storage uses PostgreSQL with SQLAlchemy async ORM:
- Campaigns, proofs, and analysis results
- User accounts and agency associations
- Audit trail for flagged issues and resolutions

### Frontend (localStorage)

Client-side caching uses localStorage with the following keys:
- `barclays_modcomms_campaigns_v3`
- `barclays_modcomms_campaign_proofs_v3`
- `barclays_modcomms_flagged_items_v3`
- `barclays_modcomms_resolved_items_v3`
- `barclays_modcomms_error_items_v3`

## License

Proprietary - Barclays Internal Use Only