Repository map

The repository keeps runtime code, deployment configuration, operational procedures, and verification together. Start with the component you are changing, then follow its contracts and validation commands.

Directory responsibilities

Directory	Responsibility	Start here
src/	Independently packaged FastAPI services	Gateway code map, RAG code map
sdk/	First-party clients, package metadata, and client tests	SDK guide
deploy/	Helm charts, cluster overlays, GitOps applications, policy, observability, and backup manifests, plus the Docker Compose evaluation stack in deploy/compose/	Chart index, customer overlay
platform/	API/config contracts, governance inputs, model catalog, eval suites, SLOs, and toolchain definitions	Feature inventory, production readiness
tenants/	Tenant onboarding specifications, sandbox policies, and deployment examples	Tenant operations
scripts/	Setup, validation, contract generation, and evidence commands	Automation guide
runbooks/	Operator procedures linked from alerts and release gates	Runbook index
docs/	Tutorials, how-to guides, reference pages, explanations, and ADRs	Documentation home
chaos/	Resilience drill definitions	Chaos drills
loadtest/	k6 scenarios, a mock runtime, and report summarization	Benchmarks and evals
results/	Tracked sample evidence and ignored current reports	Evidence and validation

The directory inventory is declared in scripts/paths.py. make paths prints it and make paths-check checks for missing or undeclared top-level directories. Directory moves still require updating paths in scripts, manifests, CI, and docs.

Runtime boundaries

The gateway and RAG service are separate deployable applications with separate Docker build contexts, dependency locks, tests, and Helm charts. Each contains a top-level app package; their test and type-check processes must remain separate.

The gateway's app/main.py assembles middleware, stores, and route registration. Route modules handle endpoint-specific behavior. Shared admission, budget settlement, error handling, and receipt recording live in app/governance.py. Changes to these controls need coverage for both successful and rejected calls, including streaming when applicable.

The RAG service's app/main.py assembles authentication, retrieval, and HTTP routes. Retrieval, embeddings, reranking, ingestion, and audit behavior have their own modules. It returns documents, context, and grounded messages; clients submit generation requests to the gateway separately.

Read the service code maps for module-level entry points and the architecture guide for deployed request flows. Do not import one service's app package from the other service or the SDK. Similar service utilities are currently packaged separately; a shared library would also need explicit Docker packaging, dependency, and test changes.

Sources and generated files

Edit this source	Refresh or check with	Result
Service routes and request schemas	make api-contract-update / make api-contract	platform/api-contracts/*.openapi.json
Service settings, chart defaults, and environment templates	make config-contract-update / make config-contract	platform/config-contracts/*.config.json
Helm values.yaml	make chart-docs-update / make chart-docs	Generated values sections in chart READMEs
Dashboard JSON under deploy/observability/dashboards/	make dashboard-update / make dashboard-check	The dashboard ConfigMap
Documentation and root runbooks	make docs-build	Ignored site/; temporary docs/runbooks/ mirror
Tenant onboarding specifications	make tenant-onboard	Ignored .out/tenants/ by default
Service requirements*.txt and root tooling requirement inputs	Hash-aware dependency resolution, then make dependency-lock-check	Corresponding checked-in dependency locks
Live measurements and validation runs	The relevant report or evidence target	Ignored current reports under results/

Runtime dependencies belong in each service's requirements.txt; test dependencies extend them through requirements-dev.txt. Root quality, docs, coverage, SDK build, and SDK test environments have separate requirement files. Keep the lock associated with each environment aligned with its input.

Files named sample-* under results/ describe report formats. They are not current validation evidence. AgentWorkflows releases require freshly generated reports.

Where to put a change

• Add API behavior to the relevant route module, with service tests and regenerated contracts when the interface changes.
• Add a reusable operator action under scripts/, expose its normal entry point in the Makefile, and document it in the relevant runbook.
• Add repository-tooling regression tests under scripts/tests/.
• Add deployment defaults to a chart and environment-specific settings to the appropriate cluster overlay.
• Add significant design decisions as an ADR, with links to the implementation and consequences for operators.
• Put temporary output under .out/ or the existing ignored report paths.

Follow the developer workflow for setup, focused tests, and the checks expected before review.