# Mod Comms — Features Overview

## Product Overview

**Mod Comms** is an AI-powered proof review tool built for Barclays by OLIVER Agency. It automates the review of marketing materials (proofs) for legal compliance, brand adherence, tone of voice, and channel suitability — replacing slow, inconsistent manual review processes with fast, structured AI analysis.

### The Problem

Marketing teams at Barclays produce hundreds of proofs across social, display, email, and print channels. Each proof must be checked against:

- Legal and regulatory requirements (FCA, ASA/CAP)
- Barclays or Barclaycard brand guidelines
- Channel-specific best practices
- Platform technical specifications

Manual review is time-consuming, error-prone, and creates bottlenecks that delay campaign launches.

### The Solution

Mod Comms deploys four specialist AI agents that analyse every proof in parallel, delivering structured feedback in seconds rather than days. A Lead Agent synthesises the results into an overall pass/fail status with clear, actionable recommendations.

---

## Multi-Agent AI System

Mod Comms uses a multi-agent architecture powered by Google Gemini 2.5 Flash. Four specialist agents run in parallel, each with deep domain knowledge loaded from a managed Knowledge Base.

### Legal Agent

- Detects financial promotions (interest rates, APR, credit products)
- Checks advertising standards compliance (ASA/CAP code)
- Verifies required disclaimers are present and legible
- Assesses FCA regulatory compliance
- Reviews terms and conditions placement
- Checks third-party content permissions and disclosures

### Brand Agent

- Validates logo usage, minimum size, clear space, and placement
- Checks colour palette against approved masterbrand colours
- Verifies typography (Barclays Effra / Arial fallback, correct weights)
- Assesses adherence to design principles and sacred assets
- Dynamically loads Barclays or Barclaycard brand specifications based on campaign settings

### Channel Best Practices Agent

- Evaluates content strategy and messaging clarity for the target platform
- Checks creative best practices (visual hierarchy, layout, engagement patterns)
- Assesses platform optimisation (algorithm, safe zones, text-to-image ratios)
- Reviews mobile-first design (legibility, touch targets, thumb-zone navigation)

### Channel Tech Specs Agent

- Verifies dimensions, resolution, and aspect ratios against platform requirements
- Checks file format, size limits, and compression
- Validates typography specifications (minimum font sizes, character counts)
- Confirms digital grid system compliance (12-column desktop, 6-column mobile)
- Checks WCAG accessibility requirements (colour contrast, legibility)

### Lead Agent

The Lead Agent synthesises all specialist reviews into a final overall status and a professional summary. It does not analyse the proof directly — it interprets and consolidates the specialist results.

---

## RAG Status System

Every agent returns a RAG (Red / Amber / Green) status:

| Status | Meaning |
|--------|---------|
| **Green** | Fully compliant, no issues found |
| **Amber** | Minor issues that should be addressed |
| **Red** | Significant issues that must be resolved |
| **Error** | Agent could not analyse with confidence |

### Overall Status Decision Logic

The Lead Agent determines the overall proof status:

1. **Requires Manual Legal Review** — Financial promotion detected
2. **Analysis Error** — Any agent returned an Error status
3. **Failed** — Any agent returned Red
4. **Passed** — All agents returned Green or Amber

---

## Campaign Management

### Campaigns

- Campaign table with name, proof count, status, creator, owning agency, and last modified date
- Create campaigns with: name, brand guidelines (Barclays / Barclaycard), campaign ID, client lead
- Agency and agency lead are pre-filled from the user's profile
- Manual status toggle between "In Progress" and "Completed"
- Show/Hide Completed toggle and "My Campaigns Only" filter
- Sortable and filterable columns

### Proofs

- Upload proofs with: name, channel, sub-channel (dependent), proof type (dependent), file
- Supported channels: Social (Meta, YouTube — 12 formats), Display (Google, Barclays.co.uk — 10 formats), Copy (AD Copy)
- Version management with full version history
- Download, delete, and re-upload capabilities
- Real-time analysis progress with agent-by-agent status updates

---

## Real-Time Analysis

Mod Comms uses WebSocket connections for live analysis:

1. User uploads a proof (image or multi-page PDF)
2. File is sent via WebSocket with campaign metadata
3. Backend rasterises PDFs to PNG images (up to 10 pages)
4. All four agents analyse in parallel via `asyncio.gather()`
5. Real-time callbacks show each agent starting and completing
6. Lead Agent synthesises results into overall status and summary
7. Complete result returned to the frontend

### Revision-Aware Analysis

When uploading a new version, the system provides previous review context to each agent. Agents can then report:

- **Resolved Issues** — Previously flagged issues that have been fixed
- **Outstanding Issues** — Issues from the previous version that remain
- **New Issues** — Issues not present in the previous version

---

## Feedback Reports & PDF Export

### Asset Detail View

- Two-column layout: proof preview (left) and agent feedback (right)
- Each agent's feedback includes RAG status badge, detailed text feedback, and actionable issues
- Issues can be marked as resolved with a resolution note (visual strikethrough)
- Issues can be flagged as incorrect feedback for audit tracking

### PDF Export

- **Single Proof Export**: Cover page with branding, proof details, preview, Lead Agent summary, and all agent feedback with RAG status
- **Campaign Export**: Consolidated report for all proofs in a campaign

---

## Knowledge Base Management

Admins can manage the reference documentation that powers each agent:

1. **Upload Source Documents** — Upload PDF/markdown brand guidelines, legal specs, or channel documentation
2. **Document Parsing** — System converts uploaded documents to structured markdown
3. **Spec Generation** — AI processes parsed documents into a unified specification
4. **Version Control** — Each processing run creates a new spec version with diff comparison
5. **Activation** — Admins can activate any spec version, which agents then use for analysis

Five knowledge bases correspond to the five agent contexts:
- Legal
- Brand (Barclays)
- Brand (Barclaycard)
- Channel Best Practices
- Channel Tech Specs

---

## Analytics Dashboard

Admin-only dashboard with key performance indicators:

- **Proofs Uploaded** — Total count
- **Pass Rate** — Percentage of proofs that passed
- **Issues Found** — Total issues across all agents
- **Time Saved** — Estimated hours saved (based on versions created from AI feedback)
- **AI Performance Summary** — AI-generated weekly trends and insights
- **Agent Performance Table** — Per-agent pass rate and average issues per proof

---

## Auditing Dashboard

Admin-only audit trail with three tabs:

- **Flags** — User-reported incorrect agent feedback (proof, agent, user comments, timestamp)
- **Resolutions** — User-resolved issues (proof, agent, original issue, resolution note, timestamp)
- **Errors** — Analysis errors (proof, error summary, timestamp)

Each audit entry links back to the specific proof and version for investigation.

---

## User Roles & Access Control

| Role | Write Access | Analytics | Auditing | Knowledge Base | Settings | User Management | Agency Filter |
|------|-------------|-----------|----------|----------------|----------|-----------------|---------------|
| Super Admin | Yes | Yes | Yes | Yes | Full | Yes | Yes |
| Oversight Admin | No | Yes | Yes | No | Read-only | No | Yes |
| Agency Admin | Yes | Yes | No | No | Full | No | No |
| Basic User | Yes | No | No | No | No | No | No |

- Azure AD / O365 SSO authentication (MSAL)
- Users without an assigned agency see a message to contact their administrator

---

## Settings & Configuration

Admin-accessible settings for managing dropdown options used across the application:

- **Channels** — Add/remove marketing channels (Social, Display, Copy)
- **Sub-Channels** — Platform-specific sub-channels dependent on parent channel
- **Proof Types** — Format types dependent on sub-channel selection
- Changes propagate immediately to all user dropdowns

---

## Technical Architecture

### Frontend
- React + TypeScript + Vite
- Tailwind CSS with Barclays design system
- MSAL (Azure AD) authentication
- WebSocket client for real-time analysis
- REST API client for CRUD operations
- localStorage persistence with versioned keys

### Backend
- FastAPI (Python) with async support
- Google Gemini 2.5 Flash API for AI analysis
- SQLAlchemy async ORM + asyncpg
- Alembic database migrations
- WebSocket endpoint for real-time analysis
- PDF rasterisation service

### Database
- PostgreSQL
- Core tables: Agencies, Users, Campaigns, Proofs, ProofVersions
- Audit tables: FlaggedItems, ResolvedItems, ErrorItems
- Configuration: DropdownOptions
- Knowledge Base: KnowledgeBases, SourceDocuments, SpecVersions, ProcessingJobs

### Infrastructure
- Azure AD for authentication
- File storage with unique keys
- CORS-configured for frontend-backend communication