# Architecture — CE Competitive Research

## System Flow

```
[User submits URL]
        ↓
[Stage 1: Brand Ingest]
  - Playwright scrape → extract brand signals
  - Claude analysis → structured brand-profile.json
        ↓
[Stage 2: Competitive Discovery]
  - Gemini (Google Search grounding) → find 20 competitors
  - Shallow profile per competitor
  - Deliver: shallow-report (editable)
        ↓
[User: edit fields / select 10 for deep research]
        ↓
[Stage 3: Deep Research (10 brands)]
  - Per brand: Playwright scrape + Gemini search + Claude analysis
  - Full deep profile per selected competitor
        ↓
[Stage 4: Scoring]
  - Score submitted brand vs. competition
  - Generate gallery-ready card data
        ↓
[Stage 5: Report Assembly]
  - Gallery of scored cards (submitted + 10)
  - Per-card click → deep-dive document
  - Branding proposal at the bottom
        ↓
[Output: HTML Report Page]
```

---

## Research Engine

### Tools
| Tool | Purpose |
|------|---------|
| Playwright | Website scraping, screenshots |
| Gemini + Google Search grounding | Competitor discovery, market research |
| Claude (Sonnet) | Analysis, scoring, proposal writing |
| CE Visual QA | `scripts/visual-qa/section-audit.py` |

### Research Modes
- **Shallow:** Name, URL, tagline, logo, position, threat level (fast, ~2min for 20 brands)
- **Deep:** Full brand analysis (5–10min per brand, run in parallel)

---

## Frontend Structure

### Pages
1. `/submit` — URL submission form
2. `/report/[id]` — Main report (shallow → selector → gallery → deep dives → proposal)
3. `/report/[id]/brand/[brand-id]` — Individual brand deep-dive

### Report Page Sections
1. **Submitted Brand Card** — Hero: extracted brand profile
2. **Competitive Map** — 20 brands, editable table
3. **Deep Research Selector** — Choose 10 of 20
4. **Research Status** — Progress on deep research
5. **Gallery** — Scored cards grid (submitted + 10)
6. **Deep Dives** — Card-click-through per brand
7. **Branding Proposal** — Designer brief

---

## Data Storage (MVP)
```
data/outputs/[report-id]/
  brand-profile.json
  competition-map.json        ← 20 competitors (shallow)
  deep-research/
    [brand-id].json           ← one per deep-researched brand
  report.json                 ← assembled report
  branding-proposal.json
  assets/                     ← logos, screenshots
```

---

## Key Decisions
- MVP: static file storage (JSON) — no DB required
- Research runs server-side, output as static JSON served to frontend
- Editable fields: frontend patches the JSON via simple API (or local storage for MVP)
- All pages CE styleguide compliant
- Visual QA before any deploy