Open Architecture
Engineering
PuniCodex
A cathedral of code generated from a single source of truth. No framework. No shortcuts. One hand-edited lexicon powers 546 temples, 357 Unicode domains, browser extensions, a mobile app, an AI oracle, and a quarter-million-assertion test battery.
Scale
By the Numbers
These figures are not marketing estimates. They are the live counts the generator writes into data-version.json every time the flywheel turns.
The Flywheel
One Source of Truth
Every temple, API response, browser extension, and AI corpus line is regenerated from canonical files. Edit the source, run the generator, run the tests, commit. The divergence gate guarantees that generated artifacts never drift.
Edit the Canonical Source
type/js/lexicon.js, js/archetypes-v2.js, platform/db/owned-domains.json, platform/blog/content/*.json, and a handful of atlases are edited by hand. Everything else is derived.
Run the Generator
npm run generate executes 46 scripts in dependency order: temples, sitemap, middleware domain map, AI corpora, store pages, OG cards, lexicon copies for every client.
Pass the Gates
npm test runs 269 suites. npm run generate:check regenerates again and fails on any dirty artifact. If the tests pass and the tree is clean, the change is valid.
Deploy Prebuilt
GitHub Actions builds and deploys via vercel deploy --prebuilt. The same generator output that passed locally is what ships.
Quality
Gates, Not Guesses
PuniCodex treats correctness as infrastructure. A page cannot ship with a missing canonical, a duplicate title, or a stale /sites/ link — the test suite fails first.
Test Infrastructure
269 declared suites, 280 test files, and roughly 250,000 assertions run serially so stateful suites do not collide.
- Lexicon Validator: 90,606 structure assertions
- Engine unit tests
- Flywheel integrity validator
- SEO regression + canonical audit
- Link checker, Lighthouse, accessibility sweep
- Red-team authenticity benchmarks
The Divergence Gate
After local edits, CI regenerates every artifact and compares the working tree. If anything differs, the build fails.
- Enforces the "never hand-edit generated outputs" rule
- Catches stale middleware, sitemap, and temple pages
- Idempotent: skipped when canonical hashes match
Format & Lint
Biome 2.5 enforces one style across the entire codebase: 2-space indentation, single quotes, LF, width 100.
Philological Accuracy
scripts/validate-accuracy.js and ACCURACY.md guard original scripts, punycode, and restoration reasoning.
SEO Hardening
Canonical links, unique titles/descriptions, HTTPS/www redirects, and robots.txt rules are enforced by tests.
Frontend
Vanilla, by Design
No React. No Vue. No build-step bloat. Every page is static HTML, shared CSS, and vanilla JavaScript served from Vercel with immutable asset caching.
Static & Shared
37 shared CSS files and 65 shared JS files power ~990 site directories. Temples share a single base template and inherit tab layouts from templates/flagship/.
css/temple-base.css,js/temple-base.jscss/punicodex-tokens.cssdesign tokensjs/px-core.jsinteraction core
Bespoke Hero Effects
Each flagship carries its own generative canvas effect. templates/flagship/effects/effects.json maps 546 temples to 533 unique canvas programs driven by js/flagship-canvas.js.
- Particle systems, storms, flames, aurora
- Culture-specific effects (e.g., Canaanite war, descent gate)
- Respects
prefers-reduced-motion
Platform
APIs, Databases & Edge
The public API is a collection of Vercel serverless functions backed by 201 handler modules. Edge middleware routes Unicode domains and canonicalizes temple URLs before a function ever runs.
33 API Functions
12 catch-all routers plus 21 specific endpoints and webhooks under api/.
201 Handlers
Modular handlers in platform/api-handlers/ covering admin, v1, v2, search, analytics, and crawler.
Edge Middleware
middleware.js routes deity domains, strips www., upgrades HTTP to HTTPS, and rewrites /sites/{id}/ to clean /{id}/ URLs.
Data Stores
- SQLite (
better-sqlite3) for local + ephemeral Vercel - Postgres for production operational state
- Redis for global rate limiting
- Vercel Blob for creative uploads when configured
Crons & Workflows
- 12 scheduled jobs in
vercel.json - Nightly evolution cycle
- Weekly red-team authenticity run
- Domain availability and crawler queues
AI & Clients
Across Every Surface
The same canonical lexicon feeds six client platforms and an AI oracle fine-tuned on PuniCodex philology.
Clients
- Type-tool browser extension (MV3)
- Authenticity / brand-protection extension (MV3)
- Mobile PWA + Capacitor Android app
- Electron desktop browser
- SDKs for JS, iOS, Android, Flutter, React Native, embedded, wearables, WordPress
Oracle & Corpus
The oracle is grounded in the lexicon, pronunciation engine, and source catalog. Behind it sits a ~233,000-line AI corpus exported from the same canonical sources.
- NVIDIA Nemotron for philosophical + pattern queries
- Instructions, chat, safety, reasoning, and oracle datasets
- Hugging Face export pipeline
Open Source
Built in the Open
PuniCodex code is released under the ISC license. Datasets are CC BY 4.0. The architecture is intentionally plain so that scholars, contributors, and sponsors can inspect exactly how every page is produced.
ISC License · CC BY 4.0 Data