How to Read These Docs

Architecture (this component) describes structure — what runs where, which namespace talks to which, how a request gets authenticated, what happens when a pod restarts. It’s organized around the platform’s own shape: ingress, auth, namespaces, the LLM gateway, storage, CI/CD, and the podcast pipeline’s internals.

Use Cases describes outcomes — what problem is solved, for whom, and why it was built that way. A use-case page reads more like "here’s what this gets you" than "here’s how it’s wired." Where a use-case needs to explain a mechanism, it links into the matching architecture page rather than restating it — so if you’re reading a use case and want the how, follow the xref.

If you’re trying to understand why a particular decision was made — why podcast-storage is a bare hostPath instead of S3, why there are four different auth patterns instead of one — the architecture pages link down to the specific decision record in iac/docs/memory/ by file path. Those are private-repo paths, cited as literal monospace text rather than links.

Everything here reflects the razizu org’s actual deployed shape as surveyed from the iac, podcast-agent, and sibling agent repos. Where a fact couldn’t be confirmed directly from a repo, it’s flagged with a NOTE: admonition rather than guessed at. Treat any single detail as a snapshot, not a live status feed — cross-check against kubectl get for anything that matters operationally right now.

Diagrams in this site are Mermaid, rendered by Antora via asciidoctor-kroki. They’re deliberately scoped to 2-3 focused views per topic rather than one exhaustive picture — the whole-fleet diagram on Architecture Overview gives you the map, and each platform/podcast page zooms into one mechanism (the auth redirect flow, the CI/CD path, the episode-generation sequence) at a size that’s still readable.