# Multimodal RAG Platform — Solution Architecture

A platform that ingests text, PDFs, images, tables, audio and video, and answers
natural-language questions across all of it with grounded, cited responses.

**Version 1.0 · 2026-08 · Status: for review**

---

## Deliverables

| Deliverable | Location |
|---|---|
| Architecture views — browsable index | [`diagrams/index.html`](diagrams/index.html) |
| Architecture views — HTML, one page per view | [`diagrams/`](diagrams/) (16 pages) |
| Architecture views — editable SVG | [`diagrams/svg/`](diagrams/svg/) (16 files) |
| Architecture views — draw.io source | [`diagrams/drawio/`](diagrams/drawio/) (16 files) |
| Solution Architecture Document | [`docs/01-solution-architecture-document.md`](docs/01-solution-architecture-document.md) |
| Architecture Decision Records | [`docs/02-architecture-decision-records.md`](docs/02-architecture-decision-records.md) |
| Diagram specifications (source of truth) | [`specs/views.json`](specs/views.json) |

Every SVG carries its diagram XML inside it: open an `.svg` from `diagrams/svg/` directly in
diagrams.net and it is fully editable, no import step. The `.drawio` files are the same
diagrams as plain source.

## The 16 views

| # | View | Form | Answers |
|---|---|---|---|
| 01 | System Context | hub-and-spoke | Who uses it, what it depends on |
| 02 | High-Level Architecture | left-to-right stages | What shape is this, in one picture |
| 03 | Layered Architecture | stacked bands | What may call what |
| 04 | Container Architecture (C4 L2) | nested boundaries | What are the deployable units |
| 05 | Multimodal Ingestion Pipeline | lanes × stages | How each modality is processed |
| 06 | Indexing & Embedding Pipeline | left-to-right stages | How a chunk becomes retrievable |
| 07 | Retrieval & Generation Flow | left-to-right stages | How a question becomes an answer |
| 08 | Data Architecture | nested zones | What is stored where, and what is rebuildable |
| 09 | Integration Architecture | inbound ǀ platform ǀ outbound | Every interface, with protocol and cadence |
| 10 | Security Architecture | trust zones | Where the boundaries are and what crosses them |
| 11 | Deployment & Infrastructure | nested regions and AZs | What runs where, what survives a failure |
| 12 | CI/CD & Environments | stages with gates | How a change reaches production safely |
| 13 | Observability & Evaluation | signal × stage matrix | How we know it works |
| 14 | RAGOps Lifecycle | closing ring | How the system improves itself |
| 15 | Critical Flow | sequence lifelines | Question to cited answer, in order |
| 16 | Core Data Model | entities and crow's feet | What is stored and how it joins |

Each view has the layout form its kind of view is supposed to have. Only view 03 uses stacked
bands, because only view 03 is about layers.

## Architecture in one page

The platform separates an **asynchronous write path** from a **synchronous read path**; they
share only storage.

**Write path.** Content lands immutably in a raw zone before anything interprets it. Six
modality-specific extraction lanes run in parallel — layout parsing with OCR fallback for
documents, vision descriptions for images, cell-structure detection for tables, transcription
with word timings for media. Every lane emits the same chunk record: a text projection, a
modality tag and a provenance pointer (page, character offsets, bounding box or timecode).
Chunks are enriched with a generated situating header, redacted, then written to three
channels — dense vectors, sparse BM25 terms, and typed rows for tables.

**Read path.** A question is screened for injection and PII, rewritten with conversation
history, then routed. Dense and lexical searches run concurrently; numeric questions
additionally generate SQL against the typed tables. Results merge by reciprocal rank fusion,
a cross-encoder reranks to the top 8, and parent expansion returns whole sections rather than
fragments. Claude Opus 5 generates with citations enabled. A grounding gate then checks every
claim against a retrieved span — unsupported claims mean one retry, then an explicit
abstention.

**What makes it grounded.** Provenance is in the data model, not bolted on afterwards; the
grounding gate is enforcement rather than instruction; and abstaining is a measured outcome
rather than a defect.

## Regenerating the diagrams

Diagrams are generated from `specs/views.json`, never hand-drawn. Geometry, box sizing and
arrow clearance are computed, and a validator fails the build on overlaps, clipped labels,
dangling edges and off-page elements.

```bash
SK=~/.claude/skills

# 1. specs -> draw.io
node $SK/architecture-deliverables/scripts/diagram.mjs specs/views.json -o build

# 2. gate: zero errors, zero warnings
node $SK/architecture-deliverables/scripts/validate.mjs build --strict

# 3. editable SVG deliverable (diagram XML embedded)
node $SK/architecture-deliverables/scripts/render.mjs \
     --in build --out diagrams/svg --format svg --embed --flat --force

# 4. plain SVG for inlining into HTML
node $SK/architecture-deliverables/scripts/render.mjs \
     --in build --out build/svg-plain --format svg --flat --force

# 5. White ground — draw.io exports SVG transparent regardless of page background
node $SK/architecture-diagram/scripts/svg-ground.mjs --dir diagrams/svg
node $SK/architecture-diagram/scripts/svg-ground.mjs --dir build/svg-plain

# 6. draw.io sources
cp build/*.drawio diagrams/drawio/

# 7. HTML pages + index
node $SK/architecture-diagram/scripts/build-html.mjs \
     --manifest specs/manifest.json --svg build/svg-plain --out diagrams
```

Requires Node.js and draw.io Desktop (`winget install JGraph.Draw`, or set `DRAWIO_PATH`).