# Architecture

How the SGGS Knowledge Base is built: three repositories, one read-only API in five bounded contexts, a pinned database, and the surfaces that show the verbatim text.

- Page: <https://docs.gurbanisoul.com/architecture/>
- Updated: 2026-09-27
- Verified against: `05086f5` on 2026-09-27
- From the Sri Guru Granth Sahib Ji — Knowledge Base wiki. Sri Guru Granth Sahib Ji is quoted verbatim, cited by Ang, and never altered.

---

The system does one thing and is built around it: it shows **Sri Guru Granth Sahib Ji exactly as
printed**, cited by Ang, and proves at every step that nothing changed. Everything else — search,
verification, the insights, the app — is read-only around that text.

In three sentences:

- **Three repositories, joined by pins.** `sggs-data` builds the database from the source Bir and
  proves it character for character; this repository pins that exact database and serves it; the
  Gurbani Soul app pins the same database and this repository's golden contract.
- **One read-only API, five bounded contexts.** Reader, search, verify, insights and knowledge — each
  declares the tables it reads, runs as its own Vercel function (or all together), and opens SQLite
  read-only and immutable. The website and the wiki call it on the same origin.
- **Every deploy is gated and proven by commit.** Nothing reaches production except through CI, and
  production is re-checked against the pin every six hours.

![Poster 01 — the system landscape: the people, the three surfaces, the one read-only API, the pinned database, and where the verbatim text comes from](https://docs.gurbanisoul.com/posters/01-system-landscape.svg)

## The pages

- [The system on one page](https://docs.gurbanisoul.com/architecture/overview/) — who uses it, the containers across the three repositories, how production runs, the five data layers.
- [Request lifecycle](https://docs.gurbanisoul.com/architecture/request-lifecycle/) — one request from the browser to SQLite and back, in the order the code does it (poster 08).
- [Bounded contexts and the gateway](https://docs.gurbanisoul.com/architecture/bounded-contexts-and-gateway/) — the five contexts, how a function serves a slice of the database, and how routing is generated so it cannot drift (poster 09).
- [Three repositories and pins](https://docs.gurbanisoul.com/architecture/three-repositories-and-pins/) — every hand-off between data, platform and app as a reviewed lock file (poster 02).
- [Search waterfall](https://docs.gurbanisoul.com/architecture/search-waterfall/) — how a query becomes results, tier by tier (poster 05); part of [Search & verification](https://docs.gurbanisoul.com/search/).
- [The insights context](https://docs.gurbanisoul.com/architecture/insights-context/) — theme networks, author and raag emphasis, Vaars and related verses: every number precomputed, descriptive only.
- [The knowledge context](https://docs.gurbanisoul.com/architecture/knowledge-context/) — raag-timing claims credited to their sources, disagreement kept, and forms taken only from headings.
- [The website](https://docs.gurbanisoul.com/architecture/website/) — a static Astro site with no framework runtime, two layouts, and the API on the same origin.
- [Security and privacy](https://docs.gurbanisoul.com/architecture/security-and-privacy/) — the defences at each layer, what is collected about readers, and the known gaps.
- [Quality and observability](https://docs.gurbanisoul.com/architecture/quality-and-observability/) — each quality, how it is measured and gated, how production is watched, and what is not yet wired.
- [Microservices roadmap](https://docs.gurbanisoul.com/architecture/microservices-roadmap/) — how the monolith became modules, then functions, and what is left.

## Read next

The decisions behind this shape are the [ADRs](https://docs.gurbanisoul.com/adr/) — especially three repositories
([ADR-0007](https://docs.gurbanisoul.com/adr/0007-three-repositories/)), the dataset by pin
([ADR-0008](https://docs.gurbanisoul.com/adr/0008-dataset-by-pin/)) and the API as functions
([ADR-0011](https://docs.gurbanisoul.com/adr/0011-api-as-functions-in-the-web-project/)). How the text is kept whole end to
end is [the integrity chain](https://docs.gurbanisoul.com/data/integrity-chain/).