# Architecture

## Runtime split

### Cloudflare Pages presentation layer

- Cinematic interface and GSAP-enhanced scroll storytelling
- Browser-native speech recognition and speech synthesis
- Local RAG demonstration and evaluation metrics
- Optional Cloudflare Worker routes for OpenAI-backed chat and translation

### Python AI service blueprint

The included `backend-blueprint` demonstrates the intended production split:

1. **LangChain** — model adapters, prompts, retrievers, tools, structured output.
2. **LangGraph** — state machine, checkpoints, durable agent workflows, human review.
3. **OpenAI Agents SDK** — agents, tools, handoffs, guardrails, sessions, tracing.
4. **Semantic Kernel** — Microsoft-oriented plugins, process integration, enterprise connectors.
5. **Transformers** — open-source text, vision, and speech model pipelines.
6. **PyTorch** — neural model training and custom inference.
7. **Scikit-learn** — classical ML, metrics, baselines, evaluation, feature pipelines.
8. **MLflow** — experiment tracking, artifacts, evaluation records, registry integration.

## Production topology

```text
Browser / Cloudflare Pages
        |
        +-- Cloudflare Worker API gateway
        |       +-- validation
        |       +-- authentication
        |       +-- rate limiting
        |       +-- secret isolation
        |
        +-- Python AI service
                +-- LangGraph orchestration
                +-- LangChain retrieval/tools
                +-- OpenAI Agents SDK runtime
                +-- Semantic Kernel enterprise adapters
                +-- Transformers / PyTorch inference
                +-- Scikit-learn evaluation
                +-- MLflow tracking
```

## Data services to add in production

- PostgreSQL for application data and sessions
- Redis for cache and job coordination
- Vector database for embeddings
- Object storage for documents and artifacts
- MLflow tracking server and artifact store
- Queue/worker system for OCR, speech, and long-running jobs