From 808326ea3668a568d9e221b62fce9aaae58160de Mon Sep 17 00:00:00 2001 From: michael Date: Mon, 15 Dec 2025 14:14:11 -0600 Subject: [PATCH] Add README and update .gitignore MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive README with project overview, architecture, setup instructions, and API documentation - Expand .gitignore with Python testing/linting, Vite cache, coverage reports, and additional IDE/OS entries πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .gitignore | 53 ++++++++++- README.md | 272 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 320 insertions(+), 5 deletions(-) create mode 100644 README.md diff --git a/.gitignore b/.gitignore index f628062..c4d9188 100644 --- a/.gitignore +++ b/.gitignore @@ -2,6 +2,7 @@ .env .env.local .env.*.local +*.local # Python __pycache__/ @@ -13,6 +14,15 @@ venv/ ENV/ env/ .venv/ +.pytest_cache/ +.coverage +htmlcov/ +.mypy_cache/ +.ruff_cache/ +*.egg-info/ +.eggs/ +pip-log.txt +pip-delete-this-directory.txt # Node node_modules/ @@ -20,14 +30,47 @@ dist/ build/ *.log npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* +.npm/ +.yarn/ -# IDE +# Vite +.vite/ +*.tsbuildinfo + +# Test coverage +coverage/ +*.lcov + +# IDE / Editors .idea/ .vscode/ *.swp *.swo -.DS_Store +*.sublime-workspace +*.sublime-project +.project +.settings/ +.classpath +*.code-workspace -# Build outputs -*.egg-info/ -.eggs/ +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Temporary files +*.tmp +*.temp +*.bak +*~ + +# Debug +.debug/ +*.pdb diff --git a/README.md b/README.md new file mode 100644 index 0000000..9a5b935 --- /dev/null +++ b/README.md @@ -0,0 +1,272 @@ +# 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 +- 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 +β”‚ β”‚ β”œβ”€β”€ services/ # Gemini API, analysis orchestration +β”‚ β”‚ β”œβ”€β”€ websocket/ # Real-time communication +β”‚ β”‚ └── main.py # FastAPI entry point +β”‚ └── 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 | +| `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": "", + "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 +``` + +## 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 + +Application state is persisted to 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