Boondoggling.ai — Software Design Document

1. One-Page Problem Summary

Core Problem Statement This system is a hybrid learning platform and prompt library for developers and technical creators who use Claude regularly but have never encountered structured AI-assisted build methodology — solving the absence of a guided, practice-based path from "I use Claude" to "I conduct Claude."

The platform delivers its solution through a scrolling homepage that tells the story of boondoggling from first principles, a /dev section of real annotated Gru projects as worked examples, a /tools prompt library where Gru and companion tools can be copied into any Claude Project, and video instruction throughout.

It occupies the space between a methodology explainer (reads but can't practice) and a raw Claude conversation (can practice but teaches nothing).

Success Condition A developer who uses Claude daily arrives, understands the solve-verify asymmetry, copies the Gru system prompt, runs it locally, and completes a real build using the methodology — without needing to ask anyone how.

2. Architecture Principles

Principle Collision Resolutions

• P1 vs. P3: P3 is primary at the publish gate. P1 is primary for content already live-and-teaching.
• P2 vs. P1: P2 is primary on format. P1 is primary on outcome. Recommended watch order is surfaced as a suggestion, not a gate.

3. Core User Flows + System Interaction Map

LEARNER ARRIVES AT /
├── BEAT 1: What is boondoggling? (conductor metaphor, solve-verify asymmetry)
├── BEAT 2: Why does it matter? (five supervisory capacities)
├── BEAT 3: How does it work? → links to /videos for depth
├── BEAT 4: Get the tool → /tools → copy Gru → paste into Claude Project
└── BEAT 5: See it in action → /dev worked examples, /videos

/tools → browse card grid → tool detail page → copy prompt → paste into Claude Project
/dev   → browse card grid (category-grouped) → open doc → read SDD in sandboxed iframe
         → optional: navigate to real build (external link)

Submission arrives (email/DM)
→ Admin creates draft in dashboard
→ Admin runs Doc Audit Prompt locally (Claude Project)
→ Decision: publish / return for revision / decline
→ Published: quality signal set, category assigned, doc visible in /dev

EXTERNAL              BOONDOGGLING.AI           LEARNER'S LOCAL ENV
────────              ───────────────           ───────────────────
YouTube          ←──  /videos
Vercel Blob      ←──  /dev (community uploads)   Claude.ai /
                 ←──  /blog (cover images)        Claude Code
Neon PostgreSQL  ←──  blog_posts                     │
                 ←──  tools                    ← Gru system prompt
                 ←──  videos                     (copied from /tools)
                 ←──  dev_docs
Vercel           ←──  deploy on push to main

4. User and Business Needs

User Needs

Operator Needs

Business Needs

5. Core Component Documentation

Component 1 — Homepage Scroll Arc

Needs: UN-1, UN-2, UN-4, BN-1

Five discrete static scroll sections. No JS-gated progression. Each beat: headline, 2–4 sentences, one contextual action. Beat 4 is the primary CTA (link to /tools/gru). Stateless — no session, no cookie, no progress tracking.

Component 2 — /tools Prompt Library

Needs: UN-2, UN-5, BN-2, ON-1–ON-3

Hybrid card grid: filesystem-driven (artifact tools in /public/tools/) + DB-driven (prompt and link tools). Each tool detail page: description, how-to-use instructions, version, copy button, clipboard fallback (<pre> + "Select all"). Character count displayed for prompt-type tools.

Component 3 — /dev Worked Examples

Needs: UN-3, UN-5, BN-1, BN-2, ON-1–ON-3

Two-source hybrid. Filesystem docs (/public/dev/WWW/, /Agents/, /Games/, with /gru/ subfolder in each) + community uploads (Vercel Blob + dev_docs DB table). Card grid groups by category, Gru-badged within each group. Full-viewport sandboxed iframe viewer. Named error component on Blob 404 or missing file.

Filesystem taxonomy:
/public/dev/
  WWW/gru/      Agents/gru/      Games/gru/

Community uploads: flat slug, category required before publish, <meta name="methodology" content="gru"> for Gru badge.

Component 4 — /videos Video Library

Needs: UN-4, UN-5, ON-1

DB-driven, identical to Musinique. YouTube embeds (youtube-nocookie.com) + Vercel Blob uploads. Search, tag filtering, pagination, pinned videos. Direct YouTube link fallback below every embed.

Component 5 — /blog

Needs: UN-5, BN-1, BN-3, ON-1

Identical to Musinique. Tiptap editor, DB-driven, Vercel Blob cover images, D3 viz hydration. Nik-authored only. Voice: argument and narrative, not reference documentation.

Component 6 — Admin Dashboard

Needs: ON-1, ON-2, ON-3

Identical auth to Musinique (HMAC-SHA256, httpOnly cookie, 7-day expiry). Tabs: Blog, Tools, Dev, Videos.

New vs. Musinique: Tools tab adds prompt_text, quality_signal, version, published fields. Dev tab adds HTML file upload → Vercel Blob, category (required before publish), methodology, quality_signal, build_url, draft/publish toggle, admin notes field (audit report).

6. External Integrations and Dependencies

Core Path Resilience No integration is a hard dependency for the core teaching path (prompt copy). That flow survives failure of every external service except Vercel.

7. Data Architecture and State Management

State model: Stateless server, stateless client. No global state store. React useState only, component-scoped. No localStorage.

Key Schema

-- New table
CREATE TABLE IF NOT EXISTS dev_docs (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  title TEXT NOT NULL,
  slug TEXT UNIQUE NOT NULL,
  description TEXT,
  blob_url TEXT NOT NULL,
  build_url TEXT,
  quality_signal TEXT DEFAULT 'community',
  category TEXT,           -- 'www' | 'agents' | 'games' — required before publish
  methodology TEXT,        -- 'gru' | null
  submitted_by TEXT,       -- display name / handle only — no email
  published BOOLEAN DEFAULT false,
  published_at TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Extended from Musinique
ALTER TABLE tools ADD COLUMN IF NOT EXISTS prompt_text TEXT;
ALTER TABLE tools ADD COLUMN IF NOT EXISTS quality_signal TEXT DEFAULT 'community';
ALTER TABLE tools ADD COLUMN IF NOT EXISTS version TEXT DEFAULT '1.0';
ALTER TABLE tools ADD COLUMN IF NOT EXISTS published BOOLEAN DEFAULT false;

-- Integrity constraint
ALTER TABLE videos ADD CONSTRAINT video_source_required
  CHECK (youtube_id IS NOT NULL OR blob_url IS NOT NULL);

Migration Run Order

1. CREATE dev_docs
2. ALTER tools (4 columns)
3. ALTER dev_docs (category, methodology)
4. ADD video CHECK constraint
5. Backfill tools (published=true, quality_signal='curated')
6. RLS policies

8. Domain Model and Entity Definitions

Ubiquitous Language

Boondoggling

The practice of conducting Claude through a build by assigning each task to the correct labor, sequencing by dependency, and making every handoff condition explicit. Reject: "A workaround"

Boondoggle Score

The sequenced, dependency-ordered output of /claude — separating Claude tasks from human tasks with copy-pasteable prompts and handoff conditions. Reject: "The build plan" — the SDD is the build plan.

Gru

The system prompt that instantiates the Gru persona in a Claude Project. Reject: "The AI" — Gru is a role, Claude is the AI.

Tool

A system prompt or HTML artifact hosted in /tools that runs in the learner's local Claude environment. Reject: "A feature of the site"

Worked Example

A complete, real Gru SDD project hosted in /dev. Reject: "A demo" — demos are synthetic.

Quality Signal

Admin-assigned curation label: Featured or Community. Reject: "A rating"

Handoff Condition

A specific, testable statement of what must be true about a Claude task's output before the next step begins. Reject: "Done criteria"

Learner

Anonymous developer/creator acquiring the methodology. Reject: "User" — no account at launch.

Contributor

Practitioner who submits an SDD or tool variant. Reject: "User"

Core Entities

• Tool — system prompt or HTML artifact. tool_type: artifact | link | prompt. prompt_text required when type=prompt. quality_signal: curated | community.
• DevDoc — real Gru SDD project. Two sources: filesystem (Nik-authored) and DB (community uploads via Blob). category required before publish. methodology: gru | null.
• BlogPost — Nik-authored article. Ported from Musinique unchanged.
• Video — YouTube embed or Blob-uploaded. CHECK constraint: at least one of youtube_id or blob_url non-null.
• AdminSession — HMAC-SHA256 signed httpOnly cookie, 7-day expiry. Never client-side.

Bounded Context One context: Content Distribution. No commerce, no identity, no analytics domain at launch.

9. API Contract Documentation

Global Behavior Guarantees

• All writes are synchronous — 200/201 means DB write completed
• All errors return { "error": "string" } — no stack traces in production
• PATCH is idempotent — POST is not (duplicate slugs return 409)
• Auth validated by middleware before any handler executes
• No rate limiting at launch (single admin, read-only public routes)

Critical Endpoint — /api/dev/upload

Five-step server-side validation: (1) content-type HTML, (2) ≤500kb, (3) HTML signature check, (4) slug unique in DB, (5) / disallowed in slug. Blob write → DB insert (sequential). Blob failure = clean error. DB failure after Blob success = orphaned file logged, admin retries safely.

10. Data Flow and Sequence Diagrams

Core Flows

Design Constraint No chatty interfaces. Every user-facing flow completes in 1–2 API calls. No async event architecture at launch.

Latency Profile

11. Component List with Priority Tags + MVS Spec

Priority Distribution MUST-BUILD: 18 items (47%) · IMPORTANT: 11 items (29%) · NICE-TO-HAVE: 7 items (18%) · EXPERIMENTAL: 3 items (8%) — user accounts, community form, Substack

MVS Verdict

The core loop is complete at MUST-BUILD only: learn the concept (homepage) → get the tool (/tools) → study real builds (/dev) → watch instruction (/videos) → read methodology (/blog) → admin publishes content without redeploying. Search, filtering, and polish (IMPORTANT) improve but do not break the experience.

Critical MUST-BUILD Items (Net-New, Not Ported)

12. Out of Scope

Binding record of decisions. Reopening requires a documented reason with a date.

13. Infrastructure and Deployment Requirements

Stack: Next.js 15 (App Router), TypeScript 5, Tailwind CSS, Vercel, Neon PostgreSQL, Vercel Blob. Identical to Musinique.

Domain: boondoggling.ai — DNS pointed to Vercel before launch.

Environment Variables

DATABASE_URL
ADMIN_PASSWORD
BLOB_READ_WRITE_TOKEN
NEXT_PUBLIC_SITE_URL=https://www.boondoggling.ai
NEXT_PUBLIC_GA_ID (optional)

Pre-Launch Checklist

• ☐ Vercel project created, domain pointed, SSL issued
• ☐ Neon Pro plan provisioned, all migrations run
• ☐ Environment variables set in Vercel dashboard
• ☐ /public/dev/ subdirectory scaffold created (WWW/, Agents/, Games/ + gru/ within each)
• ☐ Three Featured /dev docs published (one per category, all Gru-produced)
• ☐ Five videos published
• ☐ Gru system prompt published in /tools
• ☐ Admin: Doc Audit Prompt published in /tools
• ☐ Admin login tested, copy button tested, iframe sandbox verified

14. Risk Register

15. Open Questions Log

All 15 questions resolved except one:

v2 Planning Inputs

User auth provider · community submission form + privacy policy · global search index · orphaned Blob cleanup job · audit checkbox enforcement · fourth /dev category trigger · Substack newsletter