Boondoggling.ai

01 One-Page Problem Summary

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, that solves the absence of a guided, practice-based path from "I use Claude" to "I conduct Claude" 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.

02 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.

03 Core User Flows + System Interaction Map

Flow 1 — Learner's First Run (Primary)

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

Flow Honesty Test If this flow were a command-line prototype — just a README and a copy-paste prompt — would it solve the stated problem? Yes. The site is a surfacing layer, not the core value.

Flow 2 — Tools and Worked Examples (Returning Learner)

/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)

Flow 3 — Admin Submission-to-Publish

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

System Interaction Map

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

Single point of failure: Vercel (full site). All other dependencies degrade gracefully. Core teaching path (prompt copy) survives failure of every integration except Vercel.

04 User and Business Needs

User Needs

Operator Needs

Business Needs

05 Core Component Documentation

06 External Integrations and Dependencies

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

07 Data Architecture and State Management

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

Key Tables

-- 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 → 4. ADD video CHECK constraint → 5. Backfill tools (published=true, quality_signal='curated') → 6. RLS policies.

Retention

No PII beyond submitted_by (display name only). No regulatory compliance requirements at launch. Privacy policy must note that contributor display names are stored.

08 Domain Model and Entity Definitions

Ubiquitous Language

Core Entities

Bounded Context

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

09 API Contract Documentation

API Surface

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, run in order: (1) content-type HTML check, (2) ≤500kb size check, (3) HTML signature check (reads first bytes — independent of filename), (4) slug format check (/^[a-z0-9-]+$/ — no slashes), (5) slug uniqueness check in DB. Blob write → DB insert (sequential). Blob failure = clean 500. DB failure after Blob success = orphaned file logged, admin retries safely. Auth is checked before any file processing.

10 Data Flow and Sequence Diagrams

Core Flows

Learner copies Gru prompt: GET /tools → merge filesystem + DB → GET /tools/gru → tool detail page (prompt_text in DOM) → clipboard API → no server call. Survives Neon outage if Gru is filesystem artifact.

Learner views /dev doc: GET /dev → merge filesystem + DB → GET /dev/[slug] → resolve source (filesystem or Blob) → browser loads iframe src → sandboxed render. Blob 404 → named error component.

Admin uploads community doc: POST /api/dev/upload → validate → Blob put() → INSERT dev_docs (draft) → admin runs audit prompt locally → PATCH published=true.

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

Critical Net-New MUST-BUILD Items

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.

New: 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 on production URL

14 Risk Register

15 Open Questions Log

14 of 15 questions resolved. One remaining — non-blocking.

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 integration

16 Document Metadata