praxis/.ciagent/ARCHITECTURE.md

# Praxis — Architecture (Research-Refined)

> **Status:** Research-refined (Phase 0 RESEARCH stage). Informed by `.ciagent/RESEARCH.md` — web-verified vendor catalogs, GitHub metadata, official docs.

## High-Level Topology

Three-tier architecture per PRD §7:

```
┌──────────────────────────────────────────────────────────┐
│  Client (Android, iOS, Web, WhatsApp, USSD)              │
│  - Voice I/O, cached scenarios, offline scenarios        │
└────────────────┬─────────────────────────────────────────┘
                 │
┌────────────────▼─────────────────────────────────────────┐
│  Edge / Region (per market)                              │
│  - ASR + TTS (low-latency, local accent models)          │
│  - Scenario runtime + role orchestration                 │
│  - Caching layer                                         │
└────────────────┬─────────────────────────────────────────┘
                 │
┌────────────────▼─────────────────────────────────────────┐
│  Core Platform                                           │
│  - LLM tutor (long-context, persona-aware, safety-tuned) │
│  - Scenario Authoring & Tagging                          │
│  - Mastery Rubric Engine                                 │
│  - User state, progress, credentialing                  │
│  - Analytics                                             │
└──────────────────────────────────────────────────────────┘
```

## LLM Foundation (D-003, D-020 — research-verified)

Open-weights models hosted via **Ollama Cloud direct API** (`https://ollama.com/api/chat` + `OLLAMA_API_KEY`) — no local daemon required for v0.1.

| Model | Verified status | Role | Context | Mode |
|-------|-----------------|------|---------|------|
| `gemma4:cloud` | ✅ Real, current (256K ctx, Text+Image, "Low Usage" tier) | Role-play fast path / persona turns | 256K | standard |
| `deepseek-v4-flash:cloud` | ✅ Real, current (1M ctx, 284B MoE / 13B active, "Medium Usage" tier) | Coaching debrief + scenario-branch decisions | 1M | **no-think** (latency); think/max-think reserved for offline analysis |

**Post-pilot cost-reduction path:** self-host `gemma4:e4b` (edge, native audio modality, 9.6GB) on partner hardware for the ≤$3/learner/month target. Architecture must keep the model-call layer swappable (D-020).

**Notable future option:** `gemma4:e2b`/`e4b` support Text+Image+Audio input — potential future Ollama-hosted ASR for cost reduction (not v0.1; dedicated Deepgram is lower-latency + more accent-robust).

## v0.1 Component Map (research-refined minimal viable voice loop)

```
Client: React + WebRTC (Pipecat client SDK)
   │  audio in/out (WebRTC, UDP, sub-50ms)
   ▼
Pipecat server (Python)
   ├─ VAD: Silero
   ├─ STT: Deepgram Nova-3 (cloud, streaming, WebSocket)
   ├─ LLM: Ollama Cloud direct API (https://ollama.com/api/chat)
   │     ├─ gemma4:cloud         (role-play fast path)
   │     └─ deepseek-v4-flash:cloud (debrief, no-think mode)
   ├─ TTS: Cartesia Sonic (cloud, ~120ms)  ← behind interface
   │     └─ fallback: Piper (self-hosted, ~80ms)  ← R4 mitigation
   ├─ Scenario runtime: Pipecat Flows + YAML→Pydantic scenarios
   ├─ Guardrail layer: pluggable interface (v0.1: Customer Service ruleset)
   └─ Learner state: SQLite (praxis.db, single-learner, no auth)
```

**v0.1 deliberately excludes:** edge-region split, multi-market deployment, caching layer, scenario authoring tools, mastery engine, credentialing, analytics, WhatsApp/USSD surfaces.

## Latency Budget (< 600ms end-to-end — research-revised)

| Segment | Budget | Source / note |
|---------|--------|---------------|
| Client capture + WebRTC uplink | ~50ms | WebRTC UDP, Canada region |
| ASR (Deepgram Nova-3 first partial) | ~250ms | Vendor claim; **R1: measure in Phase 1** |
| LLM first token (gemma4:cloud direct API) | ~200ms | **R3: measure in Phase 1** |
| TTS first audio (Cartesia Sonic) | ~120ms | Vendor/leaderboard; **R2: measure in Phase 1** |
| WebRTC downlink + playback | ~50ms | |
| **Total (all-cloud target)** | **~670ms** | ⚠️ Marginally over 600ms |
| **Total (Piper TTS mitigation)** | **~550ms** | R4: pre-stage Piper self-hosted on pilot server |

**R4 — single biggest v0.1 technical risk:** the all-cloud three-hop path likely lands ~670ms. The TTS service MUST sit behind an interface (D-014) and Piper-on-pilot-server MUST be pre-staged as the likely production v0.1 TTS. This is the first Phase 1 spike.

## Critical Risks to Engineer Around

1. **Accent robustness** — even a great LLM fails if ASR mishears the learner. Canadian English/French accents, code-switching.
2. **Hallucinated advice in safety-sensitive domains** — health, electrical. Domain-specific guardrails, escalation, disclaimers. (v0.1 uses Customer Service path, lower risk, but architecture must support the guardrail layer.)
3. **Cost per learner per month** must stay ≤ $3 in target markets. v0.1 Canada pilot relaxes this, but architecture must not bake in assumptions that violate it.
4. **Ollama model availability / cost** — `:cloud` variants imply hosted inference; verify pricing and rate limits at research phase.

## Deployment (v0.1)

- Single-region pilot (Canada)
- LLM via Ollama Cloud direct API (no local daemon)
- ASR via Deepgram cloud (North American endpoint)
- TTS: Cartesia cloud (quality benchmark) + Piper self-hosted on pilot server (R4 latency mitigation, likely production v0.1)
- Pipecat server on single pilot host (Python)
- Client: React web app (Pipecat client SDK, WebRTC transport)
- SQLite local file (`praxis.db`) on pilot host

## Open Architecture Questions (resolved by research)

| Question (from initial ARCHITECTURE.md) | Resolution |
|------------------------------------------|------------|
| Client framework | **React + WebRTC** via Pipecat client SDK (D-015) |
| Streaming transport | **WebRTC** (Pipecat); WebSocket dev fallback (D-016) |
| ASR/TTS provider | **Deepgram Nova-3** (ASR, D-013); **Cartesia Sonic** + Piper fallback (TTS, D-014) |
| Learner state store | **SQLite** confirmed (D-007 → 0.90) |
| Ollama deployment | **Ollama Cloud direct API** (D-020) |
| Scenario definition format | **YAML DSL → Pydantic → Pipecat Flows** (D-018) |

## Open Architecture Questions (remaining for PLAN stage)

- R1-R4 latency spikes (see Risks below) — first Phase 1 tasks
- Pipecat Flows schema mapping for the one branch point (escalate vs accept) in the refund scenario
- Guardrail ruleset concrete implementation (D-019) — system-prompt template + output filter
- SQLite schema for session log + progress + scenario state
- OLLAMA_API_KEY + DEEPGRAM_API_KEY + CARTESIA_API_KEY secret management (extend `config.secrets.scopes`)