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

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

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:

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

Response Messages:

{ "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

# 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

# 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

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