Dev & 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.

---

Color key

Color	Meaning
🟣 Purple	Claude AI layer — CLAUDE.md directives and skills
🔵 Blue	Published documentation — MkDocs docs/ site
🟢 Green	Internal notes — Obsidian vault (not published)
🟠 Orange	Automation & skills — .claude/commands/
⬛ Charcoal	Application source code
⬜ Steel	Infrastructure & config — Git, GitHub Actions, VS Code

---

1 — Folder map

Where content lives across the monorepo 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"]

    %% CLAUDE.md — lavender
    style RCLAUD  fill:#ede7f6,color:#2d2d2d,stroke:#9575cd
    style BNICLAUD fill:#ede7f6,color:#2d2d2d,stroke:#9575cd
    style MPUCLAUD fill:#ede7f6,color:#2d2d2d,stroke:#9575cd
    style RLVCLAUD fill:#ede7f6,color:#2d2d2d,stroke:#9575cd
    style TCHCLAUD fill:#ede7f6,color:#2d2d2d,stroke:#9575cd

    %% Published docs — sky blue
    style BNIDOCS fill:#deeaf8,color:#2d2d2d,stroke:#5a9fd4
    style MPUDOCS fill:#deeaf8,color:#2d2d2d,stroke:#5a9fd4
    style RLVDOCS fill:#deeaf8,color:#2d2d2d,stroke:#5a9fd4
    style TCHDOCS fill:#deeaf8,color:#2d2d2d,stroke:#5a9fd4

    %% Internal vaults — mint green
    style BNIVAULT fill:#e6f4ea,color:#2d2d2d,stroke:#66bb6a
    style MPUVAULT fill:#e6f4ea,color:#2d2d2d,stroke:#66bb6a

    %% Skills — peach
    style BNISKILL fill:#fff0df,color:#2d2d2d,stroke:#e68a00

    %% App code — light grey
    style MPUSRC fill:#f0f0f0,color:#2d2d2d,stroke:#9e9e9e
    style TCHSRC fill:#f0f0f0,color:#2d2d2d,stroke:#9e9e9e

    %% Root folder — neutral
    style ROOT fill:#fafafa,color:#2d2d2d,stroke:#cccccc

---

2 — Claude CLAUDE.md hierarchy

Three levels of directives. Each level inherits 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\n━━━━━━━━━━━━━━━━━━━━\nProject Directives"]

    TCH_C["toasterchef/CLAUDE.md\n━━━━━━━━━━━━━━━━━━━━\nProject Directives"]

    SKILL["~/.claude/commands/\nOpenSourceDocs.md\n━━━━━━━━━━━━━━━━━━━━\nUser-level skill\nAvailable in every session"]

    ROOT -->|"inherits into"| ORG
    ORG -->|"inherits into"| MPU_C
    ORG -->|"inherits into"| RLV_C
    ORG -->|"inherits into"| TCH_C
    SKILL -.->|"available globally\nrun with /OpenSourceDocs"| ROOT

    style ROOT  fill:#ede7f6,color:#2d2d2d,stroke:#9575cd
    style ORG   fill:#e8ddf5,color:#2d2d2d,stroke:#9575cd
    style MPU_C fill:#f3eafc,color:#2d2d2d,stroke:#b39ddb
    style RLV_C fill:#f3eafc,color:#2d2d2d,stroke:#b39ddb
    style TCH_C fill:#f3eafc,color:#2d2d2d,stroke:#b39ddb
    style SKILL fill:#fff0df,color:#2d2d2d,stroke:#e68a00

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 — Technology stack relationships

How each tool contributes to the documentation and development pattern.

flowchart LR
    subgraph WRITE["✍️  Write"]
        VSCODE["VS Code\nEditor"]
        FOAM["Foam extension\nWiki links · Backlinks\nGraph view · Daily notes"]
        OBSIDIAN["Obsidian\nInternal vault\n(team working notes)"]
        VSCODE --> FOAM
    end

    subgraph SOURCE["📄  Source — Markdown files in git"]
        DOCS["docs/\nMkDocs source\n.md files"]
        VAULT["vault/ or\nMPowerUP Vault/\nInternal notes"]
        FOAM -->|"[[wiki links]]\nsame files"| DOCS
        OBSIDIAN -->|"separate folder\nnot published"| VAULT
    end

    subgraph BUILD["🔨  Build"]
        MKDOCS["MkDocs\nStatic site generator"]
        MATERIAL["Material theme\nSearch · Dark mode\nTabs · Admonitions"]
        MERMAID["Mermaid\nDiagrams as code\nfenced code blocks"]
        ROAMLINKS["roamlinks plugin\nResolves [[wiki links]]\nto MkDocs hrefs"]
        PRINTSITE["print-site plugin\nPDF export\nfor board / funders"]
        DOCS --> MKDOCS
        MKDOCS --> MATERIAL
        MKDOCS --> MERMAID
        MKDOCS --> ROAMLINKS
        MKDOCS --> PRINTSITE
    end

    subgraph DEPLOY["🚀  Deploy"]
        GIT["Git + GitHub\nVersion control\nSingle source of truth"]
        ACTIONS["GitHub Actions\nAuto-build on push\ndeploy.yml"]
        PAGES["GitHub Pages\nFree hosting\nHTTPS enforced"]
        GIT --> ACTIONS --> PAGES
    end

    subgraph AUTOMATE["⚙️  Automate"]
        SKILL["/OpenSourceDocs\nClaude Code skill\nScaffolds entire stack\nfor any new project"]
        CLAUDE["Claude Code\nAI coding assistant\nReads CLAUDE.md hierarchy"]
        SKILL -->|"creates"| DOCS
        SKILL -->|"creates"| GIT
        SKILL -->|"creates"| ACTIONS
        CLAUDE -->|"guided by"| SKILL
    end

    DOCS -->|"git push"| GIT
    PAGES -->|"live site\nkevinwcrump.github.io/..."| PUBLIC["🌐 Published site"]

    style FOAM    fill:#fff0df,color:#2d2d2d,stroke:#e68a00
    style SKILL   fill:#fff0df,color:#2d2d2d,stroke:#e68a00
    style CLAUDE  fill:#ede7f6,color:#2d2d2d,stroke:#9575cd
    style DOCS    fill:#deeaf8,color:#2d2d2d,stroke:#5a9fd4
    style VAULT   fill:#e6f4ea,color:#2d2d2d,stroke:#66bb6a
    style OBSIDIAN fill:#e6f4ea,color:#2d2d2d,stroke:#66bb6a
    style MKDOCS  fill:#e3ebfa,color:#2d2d2d,stroke:#7b9fd4
    style MATERIAL fill:#e3ebfa,color:#2d2d2d,stroke:#7b9fd4
    style MERMAID fill:#e3ebfa,color:#2d2d2d,stroke:#7b9fd4
    style ROAMLINKS fill:#e3ebfa,color:#2d2d2d,stroke:#7b9fd4
    style PRINTSITE fill:#e3ebfa,color:#2d2d2d,stroke:#7b9fd4
    style PAGES   fill:#ebebeb,color:#2d2d2d,stroke:#888888
    style ACTIONS fill:#ebebeb,color:#2d2d2d,stroke:#888888
    style GIT     fill:#ebebeb,color:#2d2d2d,stroke:#888888
    style PUBLIC  fill:#fafafa,color:#2d2d2d,stroke:#cccccc

---

4 — Documentation pipeline

The full journey from a note in VS Code to a live published page.

sequenceDiagram
    actor Dev as Developer
    participant VS as VS Code + Foam
    participant Git as Git (local)
    participant GH as GitHub
    participant CI as GitHub Actions
    participant GP as GitHub Pages

    Dev->>VS: Write or edit .md file
    Note over VS: [[wiki links]] resolve<br/>in Foam graph view
    VS->>Git: git add . && git commit
    Git->>GH: git push origin main
    GH->>CI: triggers deploy.yml workflow
    CI->>CI: pip install -r requirements.txt
    CI->>CI: mkdocs build --strict
    Note over CI: Mermaid diagrams rendered<br/>[[wiki links]] resolved by roamlinks<br/>PDF export generated
    CI->>GP: deploy-pages action uploads site/
    GP-->>Dev: ✅ Live at kevinwcrump.github.io/…
    Note over GP: ~60 seconds end-to-end

---

5 — /OpenSourceDocs skill

How the skill automates standing up this entire pattern on a new project.

flowchart TD
    INVOKE["/OpenSourceDocs\ninvoked in Claude Code"]

    INVOKE --> READ["Read project directory\nCLAUDE.md · README · package.json\nexisting .vscode · .gitignore · git remote"]
    READ --> ASK{"Existing notes\nfolder found?"}

    ASK -->|"yes"| QUESTION["Ask: keep separate\nvault + new docs/\nor merge?"]
    ASK -->|"no"| SCAFFOLD

    QUESTION --> SCAFFOLD["Create scaffold"]

    SCAFFOLD --> F1["docs/\nindex · architecture\nfeatures · roadmap\ncontributing"]
    SCAFFOLD --> F2["mkdocs.yml\nMaterial theme\nroamlinks · print-site"]
    SCAFFOLD --> F3[".foam/templates/\nnew-note.md"]
    SCAFFOLD --> F4[".vscode/\nextensions.json\nsettings.json\n(merged, not overwritten)"]
    SCAFFOLD --> F5[".github/workflows/\ndeploy.yml"]
    SCAFFOLD --> F6["requirements.txt\n.gitignore + site/"]

    F1 & F2 & F3 & F4 & F5 & F6 --> REPO["GitHub repo\nCreate private repo\nor push to existing"]
    REPO --> PAGES["Enable GitHub Pages\nbuild_type: workflow"]
    PAGES --> DEPLOY["Trigger first deploy\ngh workflow run deploy.yml"]
    DEPLOY --> LIVE["✅ Live docs site\n~60 seconds"]

    style INVOKE  fill:#fff0df,color:#2d2d2d,stroke:#e68a00
    style SCAFFOLD fill:#ede7f6,color:#2d2d2d,stroke:#9575cd
    style F1 fill:#deeaf8,color:#2d2d2d,stroke:#5a9fd4
    style F2 fill:#deeaf8,color:#2d2d2d,stroke:#5a9fd4
    style F3 fill:#fff0df,color:#2d2d2d,stroke:#e68a00
    style F4 fill:#f0f0f0,color:#2d2d2d,stroke:#9e9e9e
    style F5 fill:#f0f0f0,color:#2d2d2d,stroke:#9e9e9e
    style F6 fill:#f0f0f0,color:#2d2d2d,stroke:#9e9e9e
    style LIVE fill:#e6f4ea,color:#2d2d2d,stroke:#66bb6a
    style PAGES fill:#ebebeb,color:#2d2d2d,stroke:#888888
    style DEPLOY fill:#ebebeb,color:#2d2d2d,stroke:#888888

Install the skill

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