Site & Docs Architecture¶

A visual reference for the Big Nerd Idea development and documentation structure — how the tools relate, where content lives, and how the Claude setup is layered. This is the org-level architecture; application-specific architecture (MPowerUP's app stack, etc.) lives under each project.

1 — Folder map¶

Where content lives across the workspace.

flowchart TD
    ROOT["📁 ~/source/"]

    ROOT --> RCLAUD["CLAUDE.md\nOrchestrator — dispatches\nClaude to each project"]
    ROOT --> BNI["📁 big-nerd-idea/"]
    ROOT --> MPU["📁 mpowerup/"]
    ROOT --> RLV["📁 rlivn/"]
    ROOT --> TCH["📁 toasterchef/"]

    BNI --> BNICLAUD["CLAUDE.md\nOrg directives —\nshared by all devs"]
    BNI --> BNIDOCS["📁 docs/\nPublished site"]
    BNI --> BNIVAULT["📁 vault/\nInternal org notes"]
    BNI --> BNISKILL["📁 .claude/commands/\nOpenSourceDocs skill"]

    MPU --> MPUCLAUD["CLAUDE.md\nProject directives"]
    MPU --> MPUDOCS["📁 docs/\nPublished site"]
    MPU --> MPUVAULT["📁 MPowerUP Vault/\nInternal project notes"]
    MPU --> MPUSRC["📁 src/ app/ relay/\nApplication code"]

    RLV --> RLVCLAUD["CLAUDE.md"]
    RLV --> RLVDOCS["📁 docs/\nPublished site"]

    TCH --> TCHCLAUD["CLAUDE.md"]
    TCH --> TCHDOCS["📁 docs/\nPublished site"]
    TCH --> TCHSRC["📁 client/ server/ shared/\nGame code"]

2 — CLAUDE.md hierarchy¶

Three levels of directives, each inheriting downward — Claude Code reads all CLAUDE.md files from the working directory upward.

flowchart TD
    ROOT["~/source/CLAUDE.md\n━━━━━━━━━━━━━━━━━━━━\nRoot Orchestrator\nProject dispatch table\nSpawns subagents per project"]

    ORG["~/source/big-nerd-idea/CLAUDE.md\n━━━━━━━━━━━━━━━━━━━━\nOrg Directives\nTeam roster · Shared standards\nAI use policy · Subagent patterns\nVersion-controlled — both devs agree via PR"]

    MPU_C["mpowerup/CLAUDE.md\n━━━━━━━━━━━━━━━━━━━━\nProject Directives\nStack · Architecture · Conventions\nPhase status · Module reference"]

    RLV_C["rlivn/CLAUDE.md\nProject Directives"]
    TCH_C["toasterchef/CLAUDE.md\nProject Directives"]

    ROOT -->|"inherits into"| ORG
    ORG -->|"inherits into"| MPU_C
    ORG -->|"inherits into"| RLV_C
    ORG -->|"inherits into"| TCH_C

How Claude reads this

When you open a terminal in mpowerup/ and start Claude Code, it reads ~/source/CLAUDE.md → big-nerd-idea/CLAUDE.md → mpowerup/CLAUDE.md — all three, in order, before you type a single message.

3 — Documentation toolchain¶

Stage	Tools
Write	VS Code + Foam (wiki links, backlinks, graph view); Obsidian for the internal vault
Source	Markdown files in git — `docs/` is the MkDocs source; `vault/` holds internal notes
Build	MkDocs + Material theme; Mermaid for diagrams; roamlinks plugin resolves `[[wiki links]]`; print-site plugin for PDF export
Deploy	Git + GitHub as source of truth; Cloudflare Pages builds `mkdocs build --strict` on push to `main` and publishes to bignerdidea.org (most paths behind Cloudflare Access; homepage open)
Automate	The `/OpenSourceDocs` Claude Code skill scaffolds this entire stack for a new project

sequenceDiagram
    actor Dev as Developer
    participant VS as VS Code + Foam
    participant Git as Git (local)
    participant GH as GitHub
    participant CF as Cloudflare Pages
    participant Site as bignerdidea.org

    Dev->>VS: Write or edit .md file
    VS->>Git: git add . && git commit
    Git->>GH: git push origin main
    GH->>CF: push to main triggers build
    CF->>CF: mkdocs build --strict
    Note over CF: Mermaid rendered · wiki links resolved · Access-gated paths
    CF->>Site: deploy to edge
    Site-->>Dev: ✅ Live

Deploy pipeline (current)

Push to main → Cloudflare Pages builds mkdocs build --strict (Python deps from requirements.txt) and deploys to bignerdidea.org. Most paths sit behind Cloudflare Access (email one-time PIN); the homepage is open. GitHub Pages is no longer used for docs — the legacy .github/workflows/deploy.yml is retained only as a redirect publisher to close the public-leak window. Two Cloudflare checks appear on commits: Cloudflare Pages (the docs deploy) and Workers Builds (the independent CMS-auth Worker).

4 — The /OpenSourceDocs skill¶

/OpenSourceDocs (a Claude Code command) stands up the full MkDocs + Foam + docs-hosting stack on a new project: it reads the project directory, asks whether to keep or merge an existing notes folder, scaffolds docs/, mkdocs.yml, Foam templates, .vscode/ config, the deploy workflow, and requirements.txt, then creates/pushes the repo and triggers the first deploy.

Install the skill

Copy OpenSourceDocs.md to ~/.claude/commands/ on any machine and /OpenSourceDocs becomes available in every Claude Code session.