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.