Add README and update .gitignore
- 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 <noreply@anthropic.com>
This commit is contained in:
michael
parent
e97d0e935c
commit
808326ea36
2 changed files with 320 additions and 5 deletions
53
.gitignore
vendored
53
.gitignore
vendored
|
|
@ -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
|
||||
|
|
|
|||
272
README.md
Normal file
272
README.md
Normal file
|
|
@ -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": "<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
|
||||
```
|
||||
|
||||
## 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
|
||||
Loading…
Add table
Reference in a new issue