AI RAG Demo

A mock Retrieval-Augmented Generation pipeline with layered architecture, used to demonstrate ArchUnitPython architecture testing.

Setup

Install uv, then:

uv sync --all-extras

This installs the project with all dependencies (including dev/test tools) into a .venv managed by uv.

Running the Architecture Tests

uv run pytest -v

You'll see:

• 10 passing tests verifying the correct architecture
• 4 expected failures (xfail) where ArchUnitPython catches the intentional violations

Architecture

api/ -> FastAPI-style endpoints
services/ -> RAG orchestration (business logic)
retrieval/ -> Vector store & embedding (mocked)
llm/ -> LLM client (mocked)
models/ -> Data models / schemas
shared/ -> Configuration & utilities

Allowed dependency flow:

api -> services -> retrieval, llm, models
retrieval -> models, shared
llm -> models, shared
models -> shared
shared -> (nothing)

This is also codified in architecture.puml and enforced by the test suite.

Intentional Violations

Two files deliberately break the architecture to show ArchUnitPython in action:

• api/bad_shortcut.py -- API layer imports directly from retrieval/, bypassing services/
• shared/leaky.py -- Lowest layer imports from services/, creating an upward dependency

The test suite catches both via xfail-marked tests, so the suite stays green while still demonstrating the violations.