# 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@babelnexus.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 **53 hexagonal galleries** across **three floors** — 21 science hexagonal galleries (Level I), 24 literature hexagonal galleries (Level II), and 8 wisdom hexagonal galleries (Level III) — holding **842 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*. Level IV is a separate commercial storefront, not a fourth free-archive floor. Its three catalog hexagons are **Annotated Classics** (13 ebook editions), **Illustrated Classics** (15 ebook editions), and **Visual Literature** (7 ebook editions), for 35 editions total. Annotated Classics and Illustrated Classics preserve explicit editor/annotator or illustrator attribution when the edition record provides it. Visual Literature covers comics, manga, graphic adaptations, and woodcut or wordless novels in which images are essential to the narrative; this differs from Illustrated Classics, where pictures accompany a primarily textual work. Some historical illustrations may themselves be public domain, so copyright status is scoped to the individual material and edition rather than claimed for every illustration. A purchase link is emitted only for a verified Bookshop.org record, and an exact edition still being checked is shown as unavailable instead. The storefront never adds commercial editions to free archive counts or reader flows. ## 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 *hexagonal gallery* (a thematic shelf). Each node carries an `id`, a `level` (1, 2, or 3), descriptive claims, typed **edges** to other hexagonal galleries, 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 hexagonal gallery to a related one, including cross-level edges between floors. - The floors connect through a dual staircase at the center of every hexagonal gallery: 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 (hexagonal galleries, 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 hexagonal gallery view / cortex map). - `/n/` — Visual Explorer focused on one hexagonal gallery (deep-linkable). - `/t/` — 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. - `/beyond-public-domain` — Level IV, a separate bookstore with Annotated Classics, Illustrated Classics, and Visual Literature hexagons; it is not a fourth free archive floor. - `/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 storefront fallback is generated from the typed `BOOKSTORE_HEXAGONS`, and `ALL_BOOKSTORE_WORKS` exports. The prerender writes a source-derived catalog manifest; `scripts/seo-audit.mjs` compares every work, edition status, optional ISBN, and verified retailer URL in that manifest with the static sections. Storefront JSON-LD intentionally carries no free `Offer` or `isAccessibleForFree` claim. - The homepage `index.html` ships JSON-LD (`schema.org` `WebSite` + `CreativeWork`) and a no-JavaScript SSR fallback listing every hexagonal gallery, 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@babelnexus.com.