docs/ARCHITECTURE.md

Medium-MCP Architecture

System Overview

┌─────────────────────────────────────────────────────────────┐
│                      Entry Points                            │
├─────────────────┬─────────────────┬─────────────────────────┤
│   server.py     │    app.py       │      CLI                │
│   (MCP Server)  │  (Gradio UI)    │   (Commands)            │
└────────┬────────┴────────┬────────┴────────┬────────────────┘
         │                 │                 │
         ▼                 ▼                 ▼
┌─────────────────────────────────────────────────────────────┐
│                   ScraperService                             │
│  ┌─────────────────────────────────────────────────────┐    │
│  │                    Tier Chain                        │    │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐        │    │
│  │  │ Cache  │→│GraphQL │→│ HTTPX  │→│Browser │→...    │    │
│  │  │ (T0)   │ │ (T10)  │ │ (T20)  │ │ (T30)  │        │    │
│  │  └────────┘ └────────┘ └────────┘ └────────┘        │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
         │                 │                 │
         ▼                 ▼                 ▼
┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│  database   │   │  extractor  │   │   parser    │
│  (SQLite)   │   │ (Apollo/LD) │   │   (HTML)    │
└─────────────┘   └─────────────┘   └─────────────┘

---

Core Modules

Entry Points

Module	Purpose
server.py	MCP server (FastMCP)
app.py	Gradio web UI

Service Layer

Module	Purpose
src/service.py	ScraperService orchestration
src/tiers/	Tier chain pattern

Data Layer

Module	Purpose
src/database.py	SQLite caching
src/extractor.py	Content extraction
src/parser.py	HTML parsing

Infrastructure

Module	Purpose
src/http_pool.py	Connection pooling
src/resilience.py	Circuit breaker
src/validation.py	Input validation
src/security.py	Rate limiting

---

Tier Chain

Priority	Tier	Description
0	Cache	SQLite lookup
10	GraphQL	Medium API
20	HTTPX	Fast HTTP
30	Browser	Playwright
40	Wayback	Archive.org

Each tier returns TierResult(success, data, error).

---

Data Flow

URL → validate → resolve_id → tier_chain → extract → cache → render

1. Validate: Check URL format
2. Resolve: Extract post ID
3. Tier Chain: Try each tier until success
4. Extract: Parse Apollo/JSON-LD
5. Cache: Store in SQLite
6. Render: Output markdown/HTML

---

Package Structure

Medium-MCP/
├── src/
│   ├── tiers/         # Tier implementations
│   ├── validation.py  # Input validation
│   ├── security.py    # Rate limiting
│   ├── exceptions.py  # Error handling
│   └── metrics.py     # Performance metrics
├── mcp/
│   ├── schemas.py     # Pydantic models
│   └── tools/         # Tool implementations
├── ui/
│   └── styles/        # CSS modules
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
└── docs/