# Agencio Predict - Architecture

## System Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                        FRONTEND (Next.js)                       │
│                                                                 │
│  /predict (Terminal)    /predict/campaigns    /predict/trust     │
│  - PredictionCard       - CampaignPredictor   - TrustDashboard  │
│  - TrendChart           - VariantScorer       - ManipulationLog │
│  - WhyItMoved           - PersonaOverlay      - AuditTrail      │
│  - EventCluster         - HookAnalyzer        - BotDetector     │
│  - CalibrationScore     - ViralPredictor                        │
│                                                                 │
└──────────────────────────────┬──────────────────────────────────┘
                               │ REST / WebSocket
┌──────────────────────────────▼──────────────────────────────────┐
│                        API GATEWAY                              │
│                   (Next.js API Routes)                           │
└──────────────────────────────┬──────────────────────────────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         │                     │                     │
         ▼                     ▼                     ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ predict-        │  │ predict-        │  │ predict-        │
│ intelligence-   │  │ marketing-      │  │ trust-          │
│ service         │  │ service         │  │ service         │
│                 │  │                 │  │                 │
│ - Signal agg    │  │ - Campaign pred │  │ - Manipulation  │
│ - Sentiment     │  │ - A/B scoring   │  │ - Bot detection │
│ - Anomaly det   │  │ - Persona link  │  │ - Compliance    │
│ - Explanation   │  │ - Viral pred    │  │ - Audit trail   │
│ - Calibration   │  │ - Hook analysis │  │ - Risk scoring  │
└────────┬────────┘  └────────┬────────┘  └────────┬────────┘
         │                    │                     │
         └────────────────────┼─────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │    Supabase       │
                    │                   │
                    │ - PostgreSQL      │
                    │ - Auth            │
                    │ - Realtime        │
                    │ - Edge Functions  │
                    │ - Storage         │
                    └───────────────────┘
```

## Service Breakdown

### predict-intelligence-service

**Purpose**: The brain. Aggregates signals, detects anomalies, generates explanations.

**Responsibilities**:
- Pull data from prediction markets (Polymarket, Kalshi)
- Aggregate news feeds (RSS, NewsAPI)
- Social sentiment analysis (X API, Reddit API)
- Anomaly detection (volume spikes, narrative shifts, divergence)
- AI-generated explanations ("Why did this move?")
- Calibration tracking (Brier scores, accuracy over time)

**Tech**:
- Python (FastAPI) or Node.js
- LLM integration (Claude API) for explanation generation
- Scheduled jobs for data ingestion (cron / Supabase Edge Functions)

**Key Endpoints**:
```
GET  /signals/:eventId          → aggregated signals for an event
GET  /events                    → list tracked events
POST /events                    → create/track new event
GET  /events/:id/explanation    → AI-generated "why it moved"
GET  /events/:id/history        → probability timeline
GET  /calibration/report        → accuracy metrics
```

### predict-marketing-service

**Purpose**: The differentiator. Predicts marketing outcomes.

**Responsibilities**:
- Campaign success probability scoring
- A/B variant prediction (before running the test)
- Viral probability scoring
- Hook/headline effectiveness prediction
- Integration with Agencio Persona Engine
- Historical pattern matching against prior campaigns

**Tech**:
- Node.js / Python
- ML models trained on campaign performance data
- Claude API for behavioural science analysis

**Key Endpoints**:
```
POST /predict/campaign          → score a campaign concept
POST /predict/variant           → compare A/B variants
POST /predict/viral             → viral probability for content
POST /predict/hook              → score hook/headline effectiveness
GET  /predict/history/:campaignId → past predictions + outcomes
```

### predict-trust-service

**Purpose**: The moat. Detects manipulation, scores trustworthiness.

**Responsibilities**:
- Insider-like behaviour detection (abnormal timing, volume)
- Coordinated manipulation detection
- Bot-driven sentiment spike identification
- Trust scoring per event/market
- Compliance audit trail
- Flagging and alerting

**Tech**:
- Python (statistical anomaly detection)
- Time-series analysis
- Graph analysis for coordination detection

**Key Endpoints**:
```
GET  /trust/:eventId            → trust score + breakdown
GET  /trust/:eventId/flags      → flagged activities
GET  /trust/audit/:eventId      → full audit trail
GET  /trust/report              → aggregate trust report
POST /trust/alert/subscribe     → subscribe to manipulation alerts
```

## Data Flow

```
1. INGEST (every 5-15 min)
   Polymarket API → predict-intelligence-service → prediction_signals table
   NewsAPI        → predict-intelligence-service → prediction_signals table
   X/Reddit API   → predict-intelligence-service → prediction_signals table

2. PROCESS (on ingest)
   predict-intelligence-service:
     → compute aggregate probability
     → detect anomalies
     → generate explanation (if significant movement)
     → update calibration scores
     → write to prediction_events, prediction_explanations

3. TRUST CHECK (on ingest)
   predict-trust-service:
     → analyse signal patterns
     → check for manipulation indicators
     → update trust scores
     → flag if threshold breached
     → write to prediction_trust_scores

4. MARKETING (on demand)
   predict-marketing-service:
     → receive campaign/content data
     → cross-reference with persona engine
     → run prediction models
     → return scored variants with explanations

5. TRIGGERS (on state change)
   predict-triggers-engine:
     → evaluate all active rules against new state
     → check cooldowns, active hours, daily limits
     → fire matching rules
     → execute actions (Slack, email, webhook, ad platform, etc.)
     → log execution results

6. SERVE (realtime)
   Supabase Realtime → Frontend WebSocket
   → live probability updates
   → trust score changes
   → new explanations
   → rule execution notifications
```

## Infrastructure

| Component | Technology | Why |
|-----------|-----------|-----|
| Frontend | Next.js (existing Agencio stack) | Already built, extends naturally |
| API | Next.js API Routes + microservices | Familiar, scalable |
| Database | PostgreSQL (RDS in prod) | Battle-tested, realtime via triggers |
| Auth | AWS Cognito / Agencio Auth (dual) | Swappable via AUTH_PROVIDER env var |
| AI/LLM | Claude API | Explanation generation, analysis |
| Jobs | Background worker service (cron) | Data ingestion scheduling |
| Cache | Redis (ElastiCache in prod) | Signal caching, job queue, rate limits |
| Storage | MinIO (dev) / S3 (prod) | Uploads, reports, exports, backups |
| Secrets | AWS Secrets Manager (prod) / .env (dev) | No secrets in code or images |
| IAM | AWS IAM roles per service | Least-privilege access |
| Containers | Docker + Docker Compose (dev) / ECS Fargate (prod) | Consistent environments |
| CI/CD | GitHub Actions → ECR → ECS | Automated deployments |
| CDN | CloudFront | Static asset delivery |
| DNS | Route 53 | Domain management |
| Email | SES / SendGrid | Notification delivery |
| Search | PostgreSQL full-text (Phase 1) | Good enough to start |

See [10-infrastructure-deployment.md](./10-infrastructure-deployment.md) for full details.