This is the meta-architecture page, documentation of the documentation system itself. How knowledge flows, who owns what, and how decisions become reality at SEKEN. New team members read this on day one to understand the information ecosystem before diving into product specifics.
Roles in this document refer to functional responsibilities, not specific people. Current role assignments live in the brain under wiki/team/, they change as the team grows. The lifecycle and ownership patterns are stable; the names attached to them are not.
Information Architecture
The system that keeps the system honest. SEKEN runs on a small team and a lot of AI tooling. That only works if there is a single, current, contradiction-free source of truth feeding every surface, Cursor, Copilot, Claude Code, the public docs, the ops portal, the help center. This page documents how that source of truth is structured and how it stays current.
Why a separate page for this
The other 13 architecture pages describe what SEKEN is. This one describes how SEKEN knows what it is. The distinction matters because:
- AI tools need a single canonical source. Cursor and Copilot answer questions by reading whatever documentation they can reach. If the brain says one thing and the repo CLAUDE.md says another, the next AI suggestion is a coin flip. The brain ingest on 2026-04-28, a reconciliation pass over the 2026-04-26 audit findings, surfaced three such conflicts (return window, auto-confirm window, finances schema), all resolved on the same day because the structure made them visible.
- Pre-launch verification depends on it. Before customers ever hit the system, the only way to find a 7-day-vs-24-hour drift is to compare layers explicitly. The architecture audit is not optional decoration; it is the launch readiness gate.
- It future-proofs scaling. When the team grows past three people, this is what new hires onboard from. Without a documented information system, every new hire has to reconstruct the map from scratch by interviewing whoever has been around longest.
Part 1, How information flows in SEKEN
Knowledge does not move in one direction. It cycles through a small set of stations: a trigger that motivates a change, the brain that captures the canonical decision, the projections that surface that decision (docs, CLAUDE.md, code), the audit that re-verifies the running system, and the brain ingest: a reconciliation pass, that catches drift in either direction and feeds resolutions back into the brain.
Read this diagram as a cycle, not a pipeline. The arrows mark the default direction during normal operations. Brain Ingest is rendered as a distinct hex node because it is the only step that catches drift, in either direction. A spec change that never made it into code, or a code change that never made it into the spec, both surface during the same reconciliation pass.
The eight stations:
| Station | What lives here | Why it exists |
|---|---|---|
| Trigger | A KPI signal, an audit finding, a customer ticket, founder intuition | The reason any change starts |
| Brain | DECISIONS.md, architecture pages, strategy, brand, finance models, agent runbooks | The single canonical source AI tools reference |
| Docs projection | docs.pasarseken.id (via the SEKENDocs repo) | Public-readable mirror of the brain's architecture pages |
| CLAUDE.md | pasarseken/CLAUDE.md + 9 imported docs/claude/*.md files | Bridge from brain to AI coding tools (Cursor, Copilot, Claude Code) |
| Code | The pasarseken repo on main and the running system | The only thing customers actually experience |
| Audit | raw/data/architecture-audit-*.md | Quarterly snapshot of the live system compared to brain claims |
| Brain Ingest | The reconciliation pass when audits or external sources are absorbed back into the brain | The self-correction step, catches drift in both directions |
| Signal | Support tickets, ops dashboards, KPIs | Tells the brain what to update next |
This meta-system is now visible on the master map at /architecture/map under the Meta-System (Information Architecture) cluster, five nodes (Brain, CLAUDE.md bridge, docs.pasarseken.id, Quarterly Audit, Brain Ingest) sitting in the operations band, edged into the existing system clusters they govern.
The CLAUDE.md bridge
The brain doesn't directly reach AI coding tools. CLAUDE.md does.
CLAUDE.md is a single file that lives at the root of the pasarseken repo. It is a curated subset of the brain's most operationally relevant content, the architectural decisions, business rules, brand vocabulary, and current state, formatted for Cursor, Claude Code, and Copilot to read on every coding session.
When the brain updates, CLAUDE.md does not auto-update. It is regenerated manually (typically Sunday evening, when the brain has accumulated enough new decisions to justify a refresh) by running a small export pipeline. This is intentional, sudden CLAUDE.md changes mid-week could surprise AI tools that were running on cached context.
So the flow is:
brain → CLAUDE.md → AI tools → code → audit → brain ingest → brain
CLAUDE.md is the system's "eventual consistency" between the brain and the codebase. Strong consistency would require auto-regeneration on every brain change, which would be more brittle than helpful at this team size.
Part 2, How decisions become reality
A decision is not real until the running system behaves according to it. SEKEN's decision lifecycle has eight steps and at least four artifacts touched per decision. Skipping a step is the most common way for drift to enter the system.
The eight steps in plain English:
- Trigger. A decision starts somewhere, founder intuition, a user complaint, an audit finding caught during brain ingest, a KPI moving the wrong way. The trigger is logged so future-you can see why the decision happened.
- Capture in brain. Real-time. The decision goes into the locked decisions log (or the relevant strategy/finance/marketing file) with the date it was locked.
- Cross-link. Every page that references the old behaviour gets updated, not just the canonical one. Indices, taxonomies, and trackers are touched in the same pass.
- Architecture page update. If the decision is structural, touches an order state, a fee, a permission, a flow, the relevant
wiki/architecture/NN-*.mdis updated and synced to SEKENDocs. - Code change. If the decision is implementational, an entry goes into the open-questions tracker under "Pending code changes" with file/line and an owner. Engineering picks it up.
- Audit verification. The next quarterly audit re-checks the decision against the codebase, and the brain ingest pass over that audit reconciles the findings. If reality matches the brain, the decision is
live. If not, it staysdriftuntil reconciled. - Map status flag update. The corresponding node in
map-data.jsonflips fromdriftorpendingtolive. The interactive map at /architecture/map reflects this. - Open questions tracker update. If the decision closed an open question, that question moves from "Currently open" to "Recently resolved" in the open-questions tracker.
Worked example, the 24h return window
The cleanest demonstration of this lifecycle is the return window decision that closed on 2026-04-28.
| Step | Artifact | What changed |
|---|---|---|
| Trigger | raw/data/architecture-audit-2026-04-26.md ingested into brain on 2026-04-28 | Reconciliation pass surfaced that routes-orders.tsx:1734 returned a 7-day window while spec said 24 hours |
| Capture | Locked decisions log | "Return window: 24 hours, locked 2026-04-28" |
| Cross-link | 05-order-states | Time-windows table updated; alignment note added |
| Cross-link | 06-returns-disputes | Locked-decisions callout updated |
| Code change | pasarseken/routes-orders.tsx:1734 | Pending: Dev owns; tracked in open-questions |
| Audit | Next quarterly (due 2026-07-28) | Will verify code change merged via brain ingest |
| Map | map-data.json node oq-return-window-canonical | Flipped drift → resolved |
| Tracker | Open-questions tracker | Question moved into "Recently resolved 2026-04-28 cycle" |
Every same-day artifact flipped on 2026-04-28, DECISIONS, both cross-linked architecture pages, the map node, and the open-questions tracker. Only the code change is still in flight, and because it is tracked explicitly with file and line, it cannot get lost.
Reverse flow example, code-first change caught by audit
The same lifecycle runs in reverse when the code moves first. Imagine a hotfix lands in production changing the auto-confirm timer from 48h to 72h. No spec change, no DECISIONS.md entry, just a code change that has drifted from the documented 48h.
The next quarterly audit catches the drift:
- Audit script compares the pasarseken codebase against the architecture pages.
- Reports: "auto-confirm: code says 72h, docs say 48h."
- Decision required: revert code OR update docs to match.
- Decision made: update docs to 72h (assume the hotfix was correct).
- DECISIONS.md captures: "Auto-confirm raised from 48h to 72h, 2026-XX-XX."
- Architecture pages 05 and 06 are updated to reflect 72h.
- Map status flag stays green; nothing was "broken", just out of sync.
This shows the system catches drift in both directions: spec-first changes (the 24h return window above) and code-first changes (this auto-confirm example). Brain ingest is the single step where both kinds of drift converge and get reconciled.
Part 3, Information layers taxonomy
SEKEN's information lives in seven layers, each with a clear physical home and a clear owner. The layers are not strictly hierarchical, they reference each other, but each piece of information has exactly one canonical layer.
The full taxonomy with ownership and audience:
| Layer | Purpose | Lives in | Owner | Audience |
|---|---|---|---|---|
| Strategic | Decisions, brand, KPIs, roadmap, finance models | Pasarseken-AI-Brain/wiki/{DECISIONS,STRATEGY,BRAND,strategy/*,finance/*} | CEO | AI tools + founders + investors |
| Architectural | System design, flows, integrations, schema | wiki/architecture/* (canonical) + docs.pasarseken.id (public) | Shared (CEO writes, Dev verifies) | Engineers + onboarding + AI tools |
| Code-level | Implementation truth, the running system | pasarseken repo + pasarseken/CLAUDE.md + 9 imported docs | Dev | AI coding tools (Cursor, Copilot, Claude Code) |
| Operational | Runbooks, SOPs, internal processes | wiki/agents/* + ops portal modules + internal SOPs | Ops | Internal staff |
| Customer-facing | Help center articles, marketing copy, FAQ, email/WA templates | help.pasarseken.id + ops portal templates + marketing assets | Social Media Manager + Ops | Buyers + sellers |
| Audit | Verification snapshots that compare brain to code | raw/data/architecture-audit-*.md | Quarterly review (Dev + Claude) | All, ground truth check |
| Live state | What is happening right now | map-data.json status flags + ops dashboards + KPI dashboard | Map maintainer (CEO) + Ops | All |
A layer's job is to be authoritative for one thing. The brand colours are owned by Strategic, neither the architectural pages nor the customer-facing site invents a new colour. The order state machine is owned by Architectural, the help center quotes it but does not redefine it. When two layers disagree, the canonical layer wins and the other gets corrected.
Map node statuses are updated manually when status changes (e.g. mobile push goes live, an integration completes, a feature ships). The quarterly audit is the safety net, it catches drift between live state and reality whenever the manual update was missed or wrong. Live state is therefore eventually consistent, not real-time consistent; the map can lag reality by hours but never by quarters.
Part 4, Synchronization patterns
Layers stay in sync through four named patterns. Each has a frequency, a trigger, and an owner.
The four patterns:
1. Brain → Docs (manual, per change)
When a brain architecture page changes, sync to SEKENDocs in the same session. Edit brain first, convert frontmatter and links, push SEKENDocs to main, Vercel auto-deploys.
2. Brain → Code (via CLAUDE.md, per change)
When a strategic or architectural decision lands, the relevant section of pasarseken/CLAUDE.md (or its imported docs/claude/*.md) is updated. The full CLAUDE.md surface is 11 files: the lean root CLAUDE.md, plus 9 @-imported docs/claude/*.md files, plus 1 in-repo-only file (ddd-tracker.md, used by Dev as a local working tracker, not imported). Of those 11: brain owns 9 (lean root + 8 detail docs covering database, schemas, business, integrations, brand, mobile, status, testing); Dev owns 2 (architecture-ddd.md, which is imported, and ddd-tracker.md, which is not). The deploy.sh script keeps brain's 9 files in sync from brain to repo on a Sunday cadence and never touches Dev's 2.
3. Code → Brain (audit + brain ingest, quarterly)
Once a quarter, Claude reads the live pasarseken codebase and produces a fresh architecture-audit-YYYY-MM-DD.md in raw/data/. The audit compares every brain claim to actual code. The brain ingest pass that follows reconciles findings into open questions or pending code changes. As noted in Part 1, the 2026-04-28 brain ingest, not the 2026-04-26 audit, was the step that surfaced the three resolved conflicts.
4. Ops + customer signal → Brain (continuous + Friday review)
Support tickets, dispute trends, and KPI movement feed back into the brain. The Friday review is the formal touchpoint, anything from the week that should change a decision gets captured then. Case-by-case for urgent items.
Sync frequencies summarised:
| Pattern | Frequency | Trigger | Owner |
|---|---|---|---|
| Brain → Docs | Per change | Brain page edited | CEO |
| Brain → Code (CLAUDE.md) | Per change | Decision or architecture edit lands | CEO (writes), Dev (consumes) |
| Code → Brain (audit + ingest) | Quarterly | Calendar (next due 2026-07-28) | Dev + Claude |
| Ops/customer → Brain | Continuous + weekly | Ticket trend, KPI signal, Friday review | CEO |
| Help center → Ops | Case-by-case | Repeated support question | Social Media Manager |
Part 5, Why this matters
Three points worth repeating loudly.
1. AI tools need a single canonical source
Without one, Cursor and Copilot make conflicting suggestions. Cursor reads the brain via CLAUDE.md. Copilot reads the repo. If those two layers say different things, the AI suggestion that lands in the editor is whichever the model rolled the dice on. Locking the brain as canonical and propagating mechanically downstream is the only way to keep AI tooling honest at this team size.
2. Pre-launch verification caught real problems
The three conflicts caught by the 2026-04-28 ingest:
- Return window: code returned 7 days, spec said 24 hours
- Auto-confirm window: older docs said "24 hours" or "3 days", canonical was 48 hours
- Finances schema: multiple pages disagreed on whether
fin_*tables should migrate to afinancesschema or stay inpublic
None of these would have been visible without the explicit brain-ingest reconciliation between audit and brain.
3. Future-proofs scaling beyond three
SEKEN's team is currently three people, holding the CEO, Dev, and Social Media Manager roles. Onboarding the fourth person without an information system means making them ask everyone where each piece of knowledge lives. Onboarding the fourth person with an information system means handing them this page and the architecture index and saying "read these in order." The information system is what makes Tier 2 ops staffing (3-5 people) and Tier 3 ops staffing (5-10 people) tractable, see 13-scalability for the staffing tier plan.
Part 6, Tooling and automation
This system runs on a small set of tools, each owning one specific responsibility. Nothing is hidden behind magic, every sync, validation, and deploy is reproducible.
| Tool | Purpose | Lives in |
|---|---|---|
| Obsidian + GitHub | Brain editing and version control | pasarseken-AI-Brain repo |
| Cursor / Claude Code CLI | Brain ↔ docs sync | Both repos |
| CLAUDE.md | Bridge from brain to AI coding tools | pasarseken repo root |
qa-check.js | Schema validation for map-data.json | SEKENDocs/scripts/ |
qa-layout-audit.js | Position + cluster overlap validation | SEKENDocs/scripts/ |
qa-interactive-tests.js | Playwright UI tests for live map | SEKENDocs/scripts/ |
| Vercel | Auto-deploy on push to main | SEKENDocs → docs.pasarseken.id |
| Quarterly audit | Drift detection between brain and code | Manual via Claude CLI extraction prompts |
Automation roadmap by tier
The system is mostly manual today. That is deliberate at Tier 1, the cost of automation outweighs the cost of running this for three people. Each tool below has a planned automation upgrade that triggers at a specific tier.
| Concern | Today (Tier 1) | Planned upgrade | Tier trigger |
|---|---|---|---|
| Brain editing | Obsidian (CEO) + GitHub | Same, no upgrade needed | , |
| Brain → Docs sync | Manual via Cursor or Claude Code (single-session edit of both repos) | Sync script that watches wiki/architecture/*.md and copies to SEKENDocs with frontmatter conversion | Tier 2 |
| Brain → Code (CLAUDE.md) | deploy.sh script copies 9 brain-owned files into pasarseken repo | Same script + CI check that flags drift | Tier 2 |
| Validation | scripts/qa-check.js, scripts/qa-layout-audit.js, scripts/qa-interactive-tests.js (run manually) | Same scripts on Vercel preview deploys, blocking merge if QA fails | Tier 2 |
| Audit | Manual quarterly via Claude CLI extraction prompts | Same, audits stay manual; the value is in human review of findings | , |
| Deployment | Vercel auto-deploy on push to SEKENDocs main | Same | , |
| Map regeneration | node architecture-extraction-input/generate-map.mjs (manual) | Triggered by code changes touching identified surfaces | Tier 3 |
The pattern is "automate the sync once it has been done by hand five times and the steps are stable." Premature automation makes the brain feel like a build system instead of a living document.
Part 7, Failure modes and recoveries
Each layer can fail in a characteristic way. The recoveries below are not theoretical, most have been exercised at least once.
| Failure | Symptom | Recovery |
|---|---|---|
| Brain stops being canonical | AI tools give stale or contradictory advice; new code references behaviour that brain says is deprecated | Re-run the architecture audit; reconcile findings into the locked-decisions log and the relevant architecture pages via brain ingest; rebuild any drifted CLAUDE.md sections |
| Docs drift from code | docs.pasarseken.id describes a behaviour the running system no longer has | Quarterly audit + brain ingest catches this; until then, drift is flagged as ❌ on the architecture page status legend so readers know not to trust it |
| Ops knowledge stays isolated | Same support question gets answered three different ways by three different ops staff | Migrate the answer into the brain (under wiki/agents/* or help.pasarseken.id), link from ops portal macros, deprecate the ad-hoc answers |
| Customer-facing content goes stale | help.pasarseken.id shows wrong fee, wrong window, or removed feature | Marketing + Ops weekly review checks last-edited dates on KB articles; brand or fee changes in the locked-decisions log trigger a help-center sweep |
| Map status flags go stale | Risk zones in map-data.json no longer reflect reality (drift shown for resolved item, or vice versa) | Re-run the extraction prompts against the current codebase; regenerate map-data.json; sync to brain copy with $meta.synced_at refreshed |
| Open-questions tracker accumulates without resolution | The tracker grows but nothing closes; questions older than a quarter become invisible | Treat any question older than the quarterly audit cycle as a forced-decision date; force resolution at the next Friday review |
End of architecture documentation.
For questions, contact the CEO or refer to the canonical brain wiki at Pasarseken-AI-Brain.
This documentation is verified as of 2026-07-07 and regenerated weekly from the brain. Next quarterly audit due 2026-07-28.