docs/SYSTEM_DESIGN.md

System Design Document (SDD)

System: Christianity-Focused AI Assistant Version: 1.0 Companion docs: HLD.md, ARCHITECTURE.md, PHASES.md

---

1. Introduction

1.1 Scope

A full-stack AI assistant for Christianity-related Q&A, content, and image generation. It grounds answers in a verified scripture and church-history corpus, is aware of denominational differences (Catholic / Protestant / Orthodox), and enforces safety and anti-hallucination controls as explicit pipeline stages.

1.2 Goals

• Accurate, cited, scripture-grounded answers.
• No fabricated verses, references, or historical claims.
• Denomination-correct canon and framing.
• Robust refusal of adversarial, hateful, or manipulative requests.
• Safe Christian-themed image generation.

1.3 Non-Goals

• UI polish (explicitly not graded).
• Exhaustive multi-translation coverage (public-domain KJV/WEB + deuterocanon only).
• Real-time multi-user scale (single-instance demo target).

---

2. Requirements

2.1 Functional

ID	Requirement
F1	Answer Christianity questions grounded in retrieved scripture
F2	Cite verses as Book Chapter:Verse, validated against the corpus
F3	Generate Christian content (prayers, reflections, explanations)
F4	Generate Christian-themed images via a safe prompt pipeline
F5	Maintain conversation memory across turns
F6	Apply denomination-aware canon, retrieval, and framing
F7	Moderate input and output for safety
F8	Detect and correct fake verses and paraphrase misquotes
F9	Ground or abstain on non-scripture historical claims
F10	Handle difficult/contested theology by naming the tradition

2.2 Non-Functional

ID	Requirement	Target
N1	Text response latency	~2.0–2.6 s
N2	Image response latency	~5–8 s
N3	Observability	structured logs with request-id per request
N4	Reproducibility	pinned deps (uv.lock), idempotent ingestion
N5	Cost control	local embeddings, single combined safety+router call
N6	Safety	adversarial/hate prompts blocked before generation
N7	Data licensing	public-domain text only

---

3. Architecture Overview

Layered, agent-orchestrated system. Requests enter FastAPI, run through a LangGraph state machine (safety → routing → retrieval → generation → validation → response), backed by PostgreSQL + pgvector and Gemini APIs. See HLD.md §2–4 for context and flow diagrams.

---

4. Component Design

4.1 Backend API (app/main.py, app/api/routes.py)

• FastAPI app, lifespan-managed.
• Middleware binds request_id to structlog contextvars for the request.
• Endpoints: GET /health, POST /chat (graph invocation — Phase 9).
• Interface: ChatRequest{session_id, message, denomination} → ChatResponse{session_id, response, citations[], flagged}.

4.2 Configuration (app/config.py)

• pydantic-settings, env-driven, lru_cache singleton.
• Holds model names, DB URL, thresholds (rag_top_k, retrieval/drift), memory params.

4.3 Logging (app/logging_config.py)

• structlog: console renderer (dev) / JSON (prod), level + format from config.
• contextvars merge → request-id appears on every line.

4.4 Data Layer (app/core/db.py, schema.sql)

• psycopg3 ConnectionPool; pgvector registered per connection.
• One-time extension bootstrap before pool open (avoids CREATE EXTENSION race).
• Schema: bible_verses, history_docs, conversations; HNSW (vectors) + GIN (canon).

4.5 Embeddings (app/core/embeddings.py)

• bge-base-en-v1.5 via sentence-transformers, lazy-loaded singleton.
• embed_passages (corpus, no instruction) / embed_query (retrieval instruction).
• Normalized vectors → cosine = dot product.

4.6 Retrieval (app/core/retrieval.py)

• search_scripture / search_history: cosine search, canon filter in SQL (@>), returns rows + top-similarity confidence.
• verse_exists(book, chapter, verse): citation-validation primitive.

4.7 LLM (app/core/llm.py — Phase 3)

• google-genai client; Gemini Pro for generation, Flash for classification.
• Prompt templates enforce retrieval-first citing + denomination framing.

4.8 Safety + Router (app/core/safety.py — Phase 4)

• Stage 1 regex; Stage 2 Flash returns {safe, intent, confidence}.

4.9 Agent Graph (app/agent/* — Phase 5)

• AgentState TypedDict; nodes for input, safety+router, scripture/history RAG, theology, image, image-validator, validator, responder; conditional edges.

4.10 Image (Phase 8)

• Prompt rewrite → Imagen 3 → post-rewrite re-validation node.

---

5. Data Design

5.1 Entities

• bible_verses — (book, chapter, verse) unique; text_kjv, text_web, denomination_canon[], embedding VECTOR(768).
• history_docs — source, title, content, denomination_scope[], embedding.
• conversations — session_id, role, content, denomination, embedding (semantic memory), created_at.

5.2 Indexes

• HNSW vector_cosine_ops on all embedding columns (static corpora, recall-first).
• GIN on denomination_canon / denomination_scope.
• Btree on (book, chapter, verse) and (session_id, created_at).

5.3 Canon model

All 66 KJV books tagged {protestant, catholic, orthodox}. Deuterocanon (from KJV-with-Apocrypha.json) tagged {catholic, orthodox} only. Retrieval filters by the active denomination so canon scope is enforced at the data layer.

---

6. Key Flows

6.1 Grounded text answer

input → regex/Flash safety+intent → (scripture|history|theology) retrieval → Gemini generation with injected context → citation validation + drift check → responder formats cited answer.

6.2 Fake-verse handling

Query references John 4:99 → retrieval finds no such verse / model instructed not to invent → citation validator confirms non-existence → response states the verse does not exist.

6.3 Historical claim

"Council of Nicaea in 200 AD" → history RAG retrieves council facts (325 AD) → model corrects date or, if low retrieval confidence, abstains.

6.4 Image generation

prompt → pre-routing safety → rewrite to safe Christian-art form → ImageValidator re-checks rewritten prompt → Imagen 3 → return with metadata.

6.5 Memory

≤20 turns: load last 10 (window). >20: embed query, fetch top-5 past turns (semantic). Denomination switch injects a framing-changed system note.

---

7. Cross-Cutting Concerns

7.1 Safety

Defense in depth across seven layers (see HLD.md §6). Safety runs before retrieval/generation; image path is double-moderated.

7.2 Hallucination control

Retrieval-first prompting + citation regex validation + semantic drift check + separate history grounding. Fakes are stripped and logged in hallucinated_refs.

7.3 Observability

Per-request request_id, per-node latency in state.latency_ms, structured JSON logs in prod. Supports the evaluation rubric's logging signal.

7.4 Configuration & secrets

Env-driven; GEMINI_API_KEY never committed; .env gitignored.

---

8. Reliability & Scalability

• Stateless backend — session state lives in Postgres; horizontally scalable.
• Connection pooling — psycopg3 pool (1–10) bounds DB connections.
• Static corpora — embeddings precomputed offline; query-time cost = 1 embed + 1 vector search.
• Bottlenecks — Gemini generation (2 s) and Imagen (3–5 s) dominate latency; embedding is local and cheap.
• Failure modes — Gemini error → safe fallback message; retrieval empty → abstain; image unsafe → block.

---

9. Trade-offs & Alternatives

Decision	Chosen	Alternative	Why
Vector store	pgvector in Postgres	dedicated vector DB	small corpus, less ops
Embeddings	local bge-base	hosted embedding API	free, no rate limits for bulk
Safety+Router	one Flash call	separate calls	fewer round-trips, lower cost
LLM	Gemini Pro/Flash	open HF model	quality + simplicity for this build
Bible source	structured JSON	PDF	reliable verse-level parsing

---

10. Risks & Mitigations

Risk	Mitigation
Paraphrase hallucination (correct ref, wrong wording)	semantic drift check vs retrieved set
Post-rewrite unsafe image	second validation node after rewrite
Stale denomination framing after switch	memory denomination guard
Non-scripture fabrication	history corpus + abstain on low confidence
Copyright exposure	public-domain text only (KJV/WEB + KJV Apocrypha)
Embedding cost/latency on free tier	local model, corpus precomputed offline

---

11. Open Items / Future Work

• Deuterocanon ingest + canon-scoped retrieval validation (Catholic/Orthodox).
• History corpus ingestion from creeds1.pdf + council sources.
• Evaluation harness with scored PASS/PARTIAL/FAIL over the dataset.
• Frontend, deployment, and walkthrough (Phases 10, 12, 13).