# BabelNexus Architecture Summary

A machine-readable overview of how the Babel Nexus Index (https://babelnexus.com)
is built. For a content-oriented summary of the Archive itself, see
[/llms.txt](https://babelnexus.com/llms.txt).

Author: Nishan Stepak (https://www.linkedin.com/in/nishanstepak/, nishanbstepak@gmail.com).
Copyright © 2026 Nishan Stepak. All rights reserved.

## What it is

The Babel Nexus Index is a knowledge-graph explorer for the public domain. It
presents **43 chambers** across **three floors** — 19 science chambers (Level I),
16 literature chambers (Level II), and 8 wisdom chambers (Level III) — holding
**563 primary works** (overwhelmingly books, plus a handful of scientific papers
and one report), every one of them in the public domain. A built-in AI Oracle
(Google Gemini) answers free-form questions about the Archive. The project sits in
the lineage of Vannevar Bush's Memex ("associative trails," *As We May Think*,
1945), Jorge Luis Borges' *Library of Babel*, and H. G. Wells' *World Brain*.

## Repository shape

A pnpm-workspace monorepo (TypeScript, Node 24). Deployable applications live under
`artifacts/`:

- **`artifacts/nexus`** — the Index itself: the React + Vite single-page app the
  visitor sees. Tailwind for styling. Brand colours amber `#F27D26` and crimson
  `#DC143C`. This is the published product.
- **`artifacts/api-server`** — the **Nexus Oracle Channel**: a thin Express 5
  service that mediates between the browser and Google's Gemini API. The Gemini
  key lives only here.
- **`artifacts/nexus-mobile`** — an Expo / React Native companion app rendering the
  same Archive.
- **`artifacts/mockup-sandbox`** — a development-only design canvas for prototyping
  components in isolation. Not part of the published product.

Shared code lives in `lib/*` packages; utility scripts in `scripts/`. A global
reverse proxy routes traffic by path: the SPA serves `/`, the API server serves
`/api`.

## Stack

- Frontend: React + Vite + Tailwind (TypeScript).
- Mobile: Expo / React Native.
- API: Express 5; PostgreSQL + Drizzle ORM available; Zod (`zod/v4`) for
  validation; Orval for OpenAPI-driven client/codegen.
- Build: Vite for the SPA, esbuild (CJS bundle) for the server.

## Data model

The Archive is a graph defined in static JSON (`artifacts/nexus/src/data/babel_17.json`).

- **Node** = a *chamber* (a thematic shelf). Each node carries an `id`, a `level`
  (1, 2, or 3), descriptive claims, typed **edges** to other chambers, and a list
  of **evidence**.
- **Evidence** = a *work* (a public-domain book, paper, or report). Each evidence
  entry has a label (`"Attribution — Title"`), a year (BCE years use the Unicode
  minus `U+2212` so they sort and parse correctly), a classification, rights, an
  image, and source links (Project Gutenberg, Internet Archive, or Wikipedia).
- **Edges** are the "associative trails": typed connections that let a visitor walk
  from one chamber to a related one, including cross-level edges between floors.
- The floors connect through a dual staircase at the center of every chamber:
  Level I descends to Level II, Level II ascends to Level I and descends to Level
  III, and Level III ascends to Level II.

Aggregate counts (chambers, works, edges) are computed and exported from
`artifacts/nexus/src/data/stats.ts`. Component copy and metadata import from there
rather than hardcoding numbers.

## Frontend surfaces

The SPA is client-routed. Principal routes:

- `/` — Visual Explorer (the default chamber view / cortex map).
- `/n/<chamber-id>` — Visual Explorer focused on one chamber (deep-linkable).
- `/t/<encoded>` — a walkable, shareable associative trail.
- `/dashboard` — index vitals and recent activity.
- `/archive` — Level I (sciences) masterlist.
- `/literature` — Level II (literature) masterlist.
- `/wisdom` — Level III (wisdom) masterlist.
- `/intelligence` — the Oracle interface.

## The Oracle (API server)

The Oracle is the only networked backend. Flow:

1. The browser POSTs a free-form question plus a snapshot of Archive metadata to
   the project's own API server (`POST /api/oracle/ask`,
   `/api/oracle/descriptive-index`, `/api/oracle/vindication`).
2. The server attaches a system prompt and calls Google Gemini's REST API. The
   Gemini API key (`GEMINI_API_KEY` / `GOOGLE_API_KEY`) lives only on the server;
   the browser bundle never sees it.
3. The answer is returned and rendered. On any failure (missing key, upstream
   error, offline) the UI falls back to a hand-written passage so the page never
   collapses.

Health/info endpoints: `GET /api/`, `GET /api/healthz`. Because the Oracle
endpoints are public and invoke a paid model, the server size-limits request
bodies and rate-limits the heavy endpoints, and never lets user input choose the
upstream destination, model, or credentials.

## SEO & AI discoverability

- `artifacts/nexus/src/lib/seo.ts` builds per-route titles/descriptions/canonical
  metadata at runtime (`buildMeta` / `applySeo`), derived from `stats.ts`.
- `artifacts/nexus/prerender.mjs` runs after the Vite build. It snapshots every
  route's metadata, SSR fallback, and `sitemap.xml` from `buildMeta`, and syncs the
  homepage `/` index.html's title/description/Open Graph/Twitter/canonical so the
  most-shared page never ships stale counts.
- The homepage `index.html` ships JSON-LD (`schema.org` `WebSite` + `CreativeWork`)
  and a no-JavaScript SSR fallback listing every chamber, so crawlers without a JS
  runtime still see the full Archive.
- Machine-readable companions served at the site root: `/llms.txt` (content
  summary), this `/architecture.md` (architecture summary), and `/sitemap.xml`.

## Build & run

- `pnpm run typecheck` — full typecheck across all packages.
- `pnpm --filter @workspace/nexus run build` — Vite build + `prerender.mjs` for the
  SPA.
- `pnpm --filter @workspace/api-server run dev` — run the Oracle API locally.

The published deployment is the `nexus` SPA plus the `api-server`, served over
HTTPS at https://babelnexus.com.

## License

Proprietary. Copyright © 2026 Nishan Stepak. All rights reserved. The prior
CC BY 4.0 release is irrevocable for copies distributed during that window; the
current notice applies to current and future versions. Licensing inquiries:
nishanbstepak@gmail.com.