Alalaam is a work in progress. Everything here — the plan, the build status, and the historical content it describes — is draft material: not yet reliable, unverified, and subject to change without notice.
Product Requirements & Build Plan · signed off 2026-07-08 · build in progress
One historical figure at the centre of their world, drawn as an evidence graph — who they met, who they may have met, and who they only knew through books. Demo subject: al-Khwarizmi, with 23 related figures.
A TypeScript engine (packages/core) plus an oclif alalaam binary (packages/cli) owning all data operations: pull from Google Sheets, validate, derive the evidence graph, compile artifacts.
A local SKILL.md wrapping the CLI so a coding agent operates Alalaam's content through natural language instead of hand-editing data files.
Next.js Majlis Explorer + brand pages on Cloudflare Workers, reading the same core; D1 + a Durable Object give the published site live refresh on sync.
The project is built on a clone of moeghashim/PI-Starter (npm workspaces, Next.js 16 in apps/web, Biome, strict TS, CI Required checks, Codex agent layer, append-only progress.md), pushed to moeghashim/alalaam. Starter conventions win over earlier plan drafts — npm replaces pnpm, Biome replaces ESLint/Prettier, tsx --test replaces Vitest.
PI-Starter targets Vercel; Alalaam is hosted on Cloudflare. The clone gains @opennextjs/cloudflare + wrangler.jsonc + open-next.config.ts, a provider-neutral replacement for the VERCEL=1 type-check escape hatch, and docs/deploying-to-cloudflare.md mirroring the starter's Vercel doc.
The generic subset is packaged as pi-starter-cloudflare/ (doc + config templates + patch, Alalaam bindings stripped) — ready to open as a PR against the original PI-Starter repo. Delivered in v0.3.
| Layer | Choice |
|---|---|
| Language | TypeScript strict, ESM, Node 22 — shared types from core |
| Monorepo | npm workspaces: packages/core · packages/cli · apps/web · workers/realtime · skill · data · migrations |
| CLI | oclif, binary alalaam |
| Validation | zod — schema + referential integrity over Sheet rows, errors name the offending row |
| Authoring | Google Sheets (read-only service account) → committed figures.seed.json → derived graph.derived.json |
| Web | Next.js App Router on Cloudflare Workers via @opennextjs/cloudflare |
| Data / live | Cloudflare D1 (load target, not authoring) + Durable Object version-stamp broadcast |
| Styling | Handoff CSS token system ported verbatim — Editorial mood, ornament 0.5, motion on |
| Quality | Biome · tsgo --noEmit · tsx --test · Conventional Commits · one PR per task · CI gate on every PR |
| Command | Does |
|---|---|
alalaam sheet sync | Sheet → validate → compile → seed. Defaults to a dry-run diff; --write applies. |
alalaam validate | Schema + integrity checks; non-zero exit naming the offending row. |
alalaam figure add / link add | Bootstrap tools — append to the seed; when a Sheet is configured they warn and print the exact Sheet rows to paste (two-writers rule). |
alalaam compile | Seed → graph.derived.json (tiers, categories, edge textures). |
alalaam graph export | Print a subject's derived graph as JSON. |
alalaam db migrate / db push | v0.4 — apply D1 migrations; idempotent upsert + DO version bump → live refresh. |
alalaam seed:legacy | One-time import of the 23 prototype figures — asserts category parity, keeps circle notes. |
The Sheet is canonical and Sheets access is read-only, so anything written only to figures.seed.json dies at the next sheet sync --write. figure add / link add therefore warn loudly and print paste-ready Sheet rows; the dry-run diff surfaces any un-pasted local addition as a would-be deletion before it is lost.
{ en, ar }; Eastern-Arabic digits rendered at display time. Full RTL.Relationship (teacher · patron · source · peer · acquaintance · contemporary) with evidence nature (documented · plausible · booksOnly); inverses derived at read time, never authored.deriveContext — explicit edges beat the date heuristic; dates are the no-edge fallback.circleNotes: prose-only "Circle of People" chips (people outside the roster: "Thabit ibn Qurra", "None recorded by name") are stored per figure so seed:legacy loses nothing and the profile panel stays pixel-faithful. Fourth Sheet tab CircleNotes.cat per figure; seed:legacy fails loudly if the derivation disagrees on any of the 23 (medallion colour is grammar, not decoration).birthYear/deathYear; publication years stay display strings ("c.820"). Shared-city matching keys on the EN lived value; AR is display-only.Every visual property encodes a claim about the historical record. Rings = distance of certainty; edge texture = kind of evidence; weight/opacity = focus, never meaning.
Medallions are 16-segment conic rings with an Amiri initial — never a fabricated face. Full specs (sizes, arcs, dash patterns, motion) port verbatim from the handoff CSS in v0.3.
Approve with revisions — all revisions now applied to PLAN.md. Architecture, sequencing, and design-fidelity sections were sound; three substantive gaps were found against the design handoff and fixed.
circleNotes + a CircleNotes Sheet tab.figure add/link add edits would be silently destroyed by the next sync → two-writers rule.cat → parity assertion in seed:legacy, added to v0.1 success criteria.moeghashim/alalaam as project repo; Cloudflare hosting locked; Workers via @opennextjs/cloudflare (supersedes "Pages"); upstreamable Cloudflare adaptation kit as a v0.3 deliverable; tooling reconciled to starter conventions (npm, Biome, node:test).docs/handoff-v0.3.md.@alalaam/core (bilingual model + circleNotes, deriveContext grammar, validation naming offending rows, Sheets ingestion) and the alalaam CLI (sheet sync, validate, figure/link add with the two-writers warning, compile, graph export, seed legacy). seed:legacy reproduces the prototype's tiers and medallion categories for all 23 figures — the parity assertion caught a real books-prefix bug on its first run. 24 figures / 45 connections committed to data/; 29 tests green.42c4e82), fork-boundary entry appended to progress.md, full quality gate green under Node 22, CI Required checks passing on main. This status page deployed to Cloudflare Pages from plan-site/.a25e8b7) with the review revisions and pushed to main.