Survey

Architecture Decisions

54 cards ~ 5 h Deep map

Surveyed walk through the architectural choices that shape the codebase. Slow read; the cards reference each other.

  1. iris beginner 3 min

    IRIS Ecosystem Overview

    Use when: explaining IRIS to a new teammate; onboarding onto the iris-hq organisation; pitching the project to a non-technical stakeholder

  2. smo1 beginner 3 min

    Cat Mode & Personality Mapping Layer

    Use when: adding a new UI label that needs both cat and professional versions; understanding why the dashboard uses words like 'Pawprintz'; explaining the dual-mode design to a designer

  3. choco intermediate 4 min

    Factory Equipment Services

    Use when: deciding which factory service should own a new pipeline step; tracing a document from ingest to publish; wiring a new factory-equipment service alongside the existing four

  4. chronicle beginner 4 min

    Two-Service Architecture

    Use when: onboarding to the chronicle-hq monorepo; deciding which service owns a new feature; tracing a request from editor to database

  5. chronicle intermediate 4 min

    Presence Broadcast Channels

    Use when: diagnosing missing cursor updates in the editor; tuning broadcast channel buffer sizes; understanding why presence survives a single missed packet

  6. eva beginner 4 min

    Prompt Artefact Directory Layout

    Use when: scaffolding a new prompt under prompts/; auditing an unfamiliar prompt directory; wiring a guard or verifier into an existing prompt

  7. eva beginner 4 min

    eva index: README & kick-aliases Generation

    Use when: regenerating the README catalog after adding a prompt; wiring a new shell verb into the kick-aliases.sh source; understanding which section of kick-aliases.sh is hand-edited

  8. iris beginner 4 min

    Three-Tier Architecture (Core → Choco → MERIDIAN)

    Use when: explaining the deployment model; deciding which tier to integrate with; onboarding a platform engineer

  9. iris beginner 4 min

    Governance Model & Sprite Role Hierarchy

    Use when: assigning roles to new sprites; designing council governance structures; understanding decision-making authority

  10. iris intermediate 4 min

    In-Memory Registry Architecture

    Use when: understanding how iris-service stores data; debugging registry behaviour; planning the PostgreSQL migration

  11. kahn beginner 4 min

    Producer / Reader Split

    Use when: onboarding a new producer repo; debugging why Scope shows stale data; deciding where to add a new write path

  12. meridian beginner 4 min

    Client-Side Mermaid Render Pipeline

    Use when: diagrams stay rendered as code blocks instead of SVG; diagrams disappear after an Astro view-transition; switching the mermaid theme or upgrading the major version

  13. rocky beginner 4 min

    Rocky Superproject Topology

    Use when: onboarding a new submodule into rocky-hq; deciding where a new file belongs (parent vs submodule); auditing what the parent repo is allowed to contain

  14. sparki intermediate 4 min

    Inherited Pattern: Same-Origin API Proxy

    Use when: the browser's API calls lose the session cookie or hit CORS errors; changing NEXT_PUBLIC_API_URL or adding a Next.js API route in web-app; comparing sparki's rewrite with so1's BFF route handler

  15. tektree beginner 4 min

    shared-go Auth, Errors & Metrics

    Use when: starting a new Go service in the tektree workspace; matching a 4xx error code that bubbles out of any service

  16. aegis intermediate 5 min

    AegisSystem Architecture Overview

    Use when: onboarding onto the TimeChain access-control layer; debugging an unexpected AccessDenied error from AegisSystem; deciding which AEGIS subsystem owns a new security feature

  17. choco beginner 5 min

    Choco Factory Architecture Map

    Use when: onboarding to a new choco service repo; deciding which layer a new service belongs in; tracing a request from edge to vault

  18. fnp beginner 5 min

    FNP System Architecture Overview

    Use when: learning about Fork Node Protocol for the first time; understanding the three cryptographic layers; explaining FNP to non-technical stakeholders

  19. grace beginner 5 min

    VAPA & The Five SPEC Layers

    Use when: onboarding a new contributor to the GRACE protocol surface; deciding which STRATT package owns a given concern; scoping a new spec or RFC against the existing layer map

  20. grace intermediate 5 min

    Layer Architecture L0–L6

    Use when: deciding which package a new feature belongs in; reviewing a PR that imports across layer boundaries; explaining why fingerprint has zero dependencies

  21. grace beginner 5 min

    Nine Councils & Agent Roster

    Use when: routing a chain to the right gate authority; checking whether an agent is protected before assigning a step; extending a domain and choosing a council

  22. kahn intermediate 5 min

    Dual Emitter Contract

    Use when: vendoring an emitter into a sister repo; considering merging the two emitter modules; auditing forward-compat behaviour

  23. meridian intermediate 5 min

    Vite Glob Bundle-Time Data Loading

    Use when: adding a new YAML data source (units, councils, doctrines); deciding whether a runtime endpoint or build-time bundling is right; diagnosing 'fs.readFile is not a function' on the Vercel adapter

  24. nestr beginner 5 min

    Platform Components: Engine, Registry, Web, Landing, Olly, Perch

    Use when: onboarding to nestr-tools and deciding which submodule owns a change; someone describes nestr as a dependency cache with three components; checking what is live versus pre-production

  25. nestr intermediate 5 min

    Nest Dashboard: Next.js 15, better-auth Organisations, Engine JWT, Billing

    Use when: adding a dashboard route; debugging a 401 redirect or an engine call without a token; telling a prospect which dashboard screens show real data

  26. rocky beginner 5 min

    Subsystem Map SS-01 to SS-08

    Use when: deciding which subsystem owns a new feature; tracing where a console route forwards to; explaining Rocky's surface to a new operator

  27. skyflow beginner 5 min

    System Architecture Overview

    Use when: onboarding to skyflow service boundaries; deciding which service owns a new endpoint; tracing a request from client to data store

  28. smo1 beginner 5 min

    SMO1 Ecosystem Overview

    Use when: onboarding a new developer to the SMO1 codebase; explaining the architecture to a non-technical stakeholder; understanding the relationship between the six projects

  29. sparki beginner 5 min

    Service Topology: What Actually Runs

    Use when: onboarding to sparki-tools and deciding which repo a change belongs in; someone names auth-shield, deploy-loco, smithy or storm as if they were live; tracing a request from the browser to a build log

  30. tektree beginner 5 min

    Microservices Topology Overview

    Use when: onboarding to the tektree-io workspace and locating a service; deciding which subrepo to edit for a new feature

  31. tektree intermediate 5 min

    Worker Pool Job Consumer

    Use when: adding a new background job type; diagnosing a backlog on the `jobs` Redis stream

  32. tektree intermediate 5 min

    Legacy Monolith vs Microservices Split

    Use when: deciding whether a feature belongs in services/api or in a microservice; writing a migration that copies a legacy collection into the new world

  33. tnp beginner 5 min

    TNP System Architecture Overview

    Use when: orienting a new contributor to the tnp-node codebase; explaining TNP's role relative to WEAVE and VEST protocols; deciding which tnp-node module to modify for a given change

  34. vest beginner 5 min

    VEST Protocol Architecture Overview

    Use when: onboarding to the VEST codebase for the first time; explaining VEST's role in the TimeChain platform to a new team member; deciding which vest-node module owns a verification failure

  35. weave beginner 5 min

    WEAVE Protocol Architecture

    Use when: onboarding to the mesh-node codebase for the first time; explaining the WEAVE/LCB primitive to a reviewer unfamiliar with the codebase; deciding which module owns a bug in the transport vs. convergence boundary

  36. aegis advanced 6 min

    ConsistencyProof & VEST Integration

    Use when: anchoring an AEGIS proof batch to the VEST audit chain; debugging why ConsistencyProofManager.verify_proof returns false on a freshly created proof; reviewing the XOR consistency check used as a placeholder for Merkle linking

  37. iris intermediate 6 min

    5 Locked Architectural Decisions (DEC-001 to DEC-005)

    Use when: understanding why IRIS is built the way it is; arguing for or against a design change; onboarding architects onto the project

  38. kahn intermediate 6 min

    Prompt-DAG Scheduler

    Use when: designing a graph.json for a new repo; debugging why a node never starts; tuning max-parallel for a fleet run

  39. skyflow intermediate 6 min

    SSE Realtime Gateway Fanout

    Use when: adding a new push notification type; scaling realtime-gateway horizontally; debugging dropped SSE events

  40. smo1 intermediate 6 min

    purr-api Layered Architecture

    Use when: adding a new feature to purr-api; tracing a bug through the call stack; explaining the Go project structure to a new backend engineer

  41. sparki intermediate 6 min

    Engine Packages: The Shipped Path vs the Subsystems Tree

    Use when: adding a capability to api-engine and deciding where it goes; someone cites subsystems/score or subsystems/loco as running code; debugging which package owns a failing API route

  42. stratt intermediate 6 min

    Layered Architecture L0–L6

    Use when: deciding which package owns a new responsibility; tracing a feature from CLI down to the identity layer; onboarding a contributor to the monorepo

  43. tektree intermediate 6 min

    API Gateway Request Flow

    Use when: debugging a 401 or 429 response that never reached a downstream service; adding a new route group that proxies to a backend service

  44. tnp intermediate 6 min

    Fork Detection & Storage Analysis

    Use when: deciding whether to prune stale branches before storage overhead exceeds the configured cap; tuning max_active_timelines based on measured fork probability; debugging unexpectedly high storage usage in a multi-branch deployment

  45. traceo beginner 6 min

    Two-Service MCP & Engine Architecture (as deployed)

    Use when: deciding which service owns a new endpoint; debugging cross-service request flow; onboarding to the Traceo backend; adding a route and wondering why it 404s in production

  46. nestr advanced 7 min

    pellets-registry: Receiver, Namespace Claims, Witnessed Transparency Log

    Use when: explaining what registry.nestr.tools does today versus by design; configuring the Rekor backend and witness pool; a customer asks how to publish or claim a namespace

  47. rocky advanced 7 min

    Provision-then-RALPH End-to-End

    Use when: diagnosing where the e2e chain broke after a phase ref-bump; explaining the OSS-parity contract to a self-hoster; tracing which HATCH events should appear in a healthy run

  48. stratt advanced 7 min

    Dependency DAG & Blast Radius

    Use when: estimating the impact of changing a shared rule; diagnosing a cycle reported by `stratt validate`; writing CI gates that block on fan-out size

  49. grace advanced 8 min

    Primer Domain Extension Pipeline

    Use when: extending STRATT to a new vertical domain; auditing the neuro-domain rollout for SPEC alignment; scoping the next domain (finance, legal, nutrition...)

  50. smo1 intermediate 8 min

    Billing via TOLL: Decision Accepted, Polar Still in Code

    Use when: debugging why a user's tier did not update after payment; someone asks whether smo1 bills through Polar or TOLL; touching any billing route, the Polar webhook, or users.tier

  51. smo1 intermediate 8 min

    Database Architecture

    Use when: writing a migration or a production SQL check; deciding whether data belongs in Postgres, Redis or the click store; explaining which tables the TOLL switch leaves dormant

  52. smo1 advanced 8 min

    TOLL Sell-Through: users.tier as a Cache of Entitlements

    Use when: implementing or reviewing the purr-api TOLL sell-through; reasoning about when a smo1 tier change becomes visible; a paid user was downgraded or not upgraded and you need the intended rule

  53. playbook advanced 13 min

    RS-DL-003: the trust core, end to end

    Use when: you need the plan for taking the loop from 'runs' to 'independently proven', phase by phase; working on IRINA, the canary e2e, delegation contracts, Mac-lab journeys or the TOLL path proof; checking which RS-DL-003 phase a piece of work belongs to and what closes it

  54. playbook advanced 14 min

    RS-DL-004: the revenue loop — one rail, demand first, money that stays consistent

    Use when: deciding how an app should take money, and in what order relative to other apps; working on TOLL P3, the estate gate graph, the demand gate, revenue integrity or per-app economics; explaining which money acts an agent may measure and propose, and which stay human for ever