Architecture Documentation Audit Report
Audít_Répórt // Láyered_Gatekéeeping
ᚠ ᛫ ᛟ ᛫ ᚱ ᛫ ᛒ ᛫ ᛟ ᛫ ᚲ
This audit verifies that architectural information is correctly layered per the 3-Layer Documentation Strategy. Proprietary details belong only in api/; investor-facing and SDK-consumer docs must not leak Layer 3 content.
Layer Definitions (from api/README.md)
| Layer | Audience | Source | Rule |
|---|---|---|---|
| 1. The Dream | Investors, Gamers, Non-Technical | forboc.ai, forbocai.github.io | Sci-Fi metaphors only. Never APIs, Latency, Vector DBs. Feel like magic. |
| 2. The Interface | Game Developers (SDK Consumers) | forbocai (Fern Docs) | What (inputs/outputs), not How. Black box. Gatekeep logic. |
| 3. The Machine | Internal Core Team | api/ (this repo) | Absolute technical clarity. Split-Brain, Vector DB, Rule Engine, Pure Logic. |
Findings & Fixes Applied
1. Soul Storage: IPFS vs Arweave (CONFLICT — FIXED)
Authoritative design (SOUL_STORAGE_AND_ENCRYPTION_DESIGN.md): Souls use Arweave (pay once, permanent). IPFS is rejected for Souls due to pinning/ongoing cost.
Files that incorrectly referenced IPFS for Soul storage: - forbocai/fern/docs/pages/soul.mdx — “IPFS-based” - forbocai/fern/docs/pages/concepts.mdx — IPFS in Soul storage options - sdk/README.md — “IPFS Pinning”, “IPFS” - forbocai/README.md — “IPFS” - forbocai.github.io/readme.md — “IPFS” in Encapsulated Souls - forbocai.github.io/posts/x/20260130/thread.md — “Export their Soul to IPFS” - Forboc/notes/TODOs/system-todo.md — IPFS in Soul export
Fix: Update all to reference Arweave (or “permanent decentralized storage”) per design. Layer 2 docs may use neutral language and link to the design doc for details.
2. Layer 2 Leaking Layer 3 (Proprietary Info — FIXED)
Forbidden in Layer 2: Split-Brain, Vector DB, IndexedDB (as implementation detail), Rule Engine, Pure Logic, “API is the Law”, “API has no models”.
Files that leaked: - forbocai welcome.mdx — “Split-Brain architecture” in Development Cycle - forbocai welcome.mdx — “SDK (The Vessel)” / “API (The Truth)” diagram - forbocai concepts.mdx — IndexedDB, RAG pipeline (Observe/Embed/Store/Recall), detailed Bridge flow - forbocai agent.mdx — “API (The Law)” flow, “API returns behavioral directive (pure logic)” - sdk README.md — “The Neural Grid” with “[SLM + VectorDB]” vs “[Stateless Rules]”, “The VESSEL” vs “The TRUTH”
Fix: Soften language. Describe what components do (Cortex runs locally, Memory stores, Bridge validates) without revealing Split-Brain, Vector DB, or API internals.
3. Investor-Facing (forbocai.github.io) — REVIEWED
Layer 1 rule: Never mention APIs, Latency, Vector DBs. Sci-Fi metaphors.
Status: - index.html meta: “neuro-symbolic AI” — technical term; consider “living AI” or “autonomous consciousness” for pure investor view - posts/x/thread.md: Very technical (Cortex, RAG, Neuro-Symbolic Bridge, IPFS) — appropriate for developer/technical audience, not pure investor - Technology.js: Good — “Synthetic Soul”, “Ghost in the Shell”, no API/Vector DB - Vision.js: Good — Solana, Metaplex, $FAI, sovereign ownership - Forboc.AI/investors: Clean — vision, Seed Round, no technical leaks
Fix: Meta descriptions on forbocai.github.io may retain “neuro-symbolic” for developer discovery; investor-facing pages (e.g. /investors) should avoid it. X thread targets developers—acceptable.
4. Forboc Repo — OK
- system-architecture.md, CLIENT_ARCHITECTURE.md: Game-engine only, no ForbocAI proprietary leak
- system-todo.md: Internal integration doc; references SDK/IPFS for implementation—acceptable for internal notes. Updated to Arweave per Soul design.
- mechanics/services/api/README.md: RTK Query (game backend), not ForbocAI API—fine
Summary of Edits Made
| Repo | File | Change |
|---|---|---|
| forbocai | fern/docs/pages/soul.mdx | IPFS → Arweave; add design-doc reference |
| forbocai | fern/docs/pages/concepts.mdx | Soul storage: IPFS → Arweave; soften Layer 3 leaks |
| forbocai | fern/docs/pages/welcome.mdx | Remove Split-Brain; soften SDK/API diagram |
| forbocai | fern/docs/pages/agent.mdx | Remove “API (The Law)” diagram; keep integration flow generic |
| forbocai | fern/docs/pages/memory.mdx | Remove LanceDB/IndexedDB implementation details where possible; keep API |
| forbocai | README.md | IPFS → Arweave |
| sdk | README.md | IPFS → Arweave; remove Neural Grid proprietary detail |
| forbocai.github.io | readme.md | IPFS → decentralized storage (Arweave) |
| forbocai.github.io | posts/x/thread.md | IPFS → Arweave |
| Forboc | notes/TODOs/system-todo.md | IPFS → Arweave |
Audit date: 2026-02-06