• Repository Structure

    This repository uses a pnpm workspace to manage multiple packages and projects. Understanding the structure will help you navigate the codebase and know where to make changes.

    Top-Level Directories

    content/

    All course materials and internal documentation live here.

    • content/courses/ — Course content organized by course (e.g., advanced-ui/, advanced-figma/)
    • content/handbook/ — Internal documentation and style guides (this handbook)
    • content/workspace/ — Workspace-specific content, proposals, and ideas

    Most content is written in Chalk (.chalk files), which is our content authoring format. See the Chalk documentation for details.

    apps/

    Internal applications for operations, planning, and feedback. These are standalone tools used day-to-day.

    • apps/hub/ — Internal ops hub
    • apps/launch-desk/ — CMO mission control for cohort launches
    • apps/leads/ — Preview lead outreach tool
    • apps/feedback/ — Cohort feedback review and email tool
    • apps/school-planner/ — Course planning tool (Svelte)
    • apps/project-board/ — Kanban-style project management tool
    • apps/dashboard/ — Analytics dashboard (Observable-based)

    packages/

    Shared libraries and utilities that support our work. These are managed as pnpm workspace packages.

    • packages/chalk/ — The Chalk build system and content processor
    • packages/workbench/ — Interactive UI demo tool for educational content
    • packages/blueprint/ — Layered UI component library for Workbench
    • packages/design-system/ — Shared design tokens and styles
    • packages/db/ — Database schema and migrations

    Each package typically has its own package.json, dependencies, and development scripts. See Tools and Packages for more details.

    websites/

    Source files for our public-facing websites.

    • websites/buttonschool.com/ — Main Button School website
    • websites/chalkboard.buttonschool.com/ — Chalkboard preview tool
    • websites/handbook.buttonschool.com/ — This handbook (public version)
    • websites/learn.buttonschool.com/ — Learning platform
    • websites/uimc.buttonschool.com/ — UI Masterclass website
    • websites/relay/ — Edge relay

    Each website has its own build configuration and deployment setup.

    previews/

    Course preview sites for prospective students.

    • previews/advanced-figma/ — Advanced Figma preview
    • previews/advanced-ui/ — Advanced UI preview
    • previews/ai-coding/ — AI Coding preview
    • previews/clubs/ — Clubs preview

    tools/

    Standalone tools for generating, exporting, and managing things.

    • tools/course-exporter/ — Tool for exporting courses as zip files
    • tools/invoice-generator/ — MCP-based invoice generator
    • tools/invoice-downloader/ — Internal tool for downloading invoices

    lab/

    Experiments, prototypes, and internal utilities.

    • lab/syllabus-generator/ — MCP-based syllabus PDF generator
    • lab/chalk-review/ — Internal tool for reviewing chalk content
    • lab/skills-reader/ — Static site generator for reading agent skills
    • lab/create-wireframe/ — Wireframe prototype scaffolding tool
    • lab/stuff/ — Native macOS app (Swift) with MCP server
    • lab/codepen-archive/ — Archive of CodePen demos and examples

    Root-Level Files

    Configuration Files

    • package.json — Root package configuration and workspace scripts
    • pnpm-workspace.yaml — Defines the pnpm workspace structure
    • pnpm-lock.yaml — Lock file for dependencies
    • Brewfile — Homebrew packages installed by setup.sh
    • setup.sh — Initial setup script for new team members

    Documentation

    • README.chalk — Repository overview (rendered on GitHub)
    • .gitignore — Git ignore patterns

    Other Files

    Most other files in the root are configuration for build tools, linters, or deployment. If you’re just working on content, you typically don’t need to modify these.

    pnpm Workspace Structure

    This repository uses pnpm workspaces to manage multiple packages. The workspace is defined in pnpm-workspace.yaml and includes:

    • All apps in apps/
    • All packages in packages/
    • All tools in tools/
    • All websites in websites/
    • All previews in previews/
    • All lab projects in lab/

    This means:

    • Dependencies are installed from the root with pnpm install
    • Packages can depend on each other using workspace protocol (workspace:*)
    • Scripts can be run from the root or individual packages
    • Dependencies are hoisted and shared where possible

    When to Use Each Directory

    Use content/ when:

    • Creating or editing course materials
    • Writing handbook documentation
    • Adding new lessons or guides

    Use apps/ when:

    • Working on internal operations tools (hub, launch-desk, leads, feedback, etc.)
    • Building or maintaining planning and management tools

    Use packages/ when:

    • Working on shared libraries (Chalk, design system, database, etc.)
    • Fixing bugs in Chalk, Workbench, or other shared tools
    • Adding features to existing shared packages

    Use websites/ when:

    • Making changes to public-facing websites
    • Updating site content or styling
    • Working on deployment configurations

    Use tools/ when:

    • Building standalone generators, exporters, or utilities
    • Working on invoice, course export, or similar operational tools

    Use lab/ when:

    • Experimenting with new ideas
    • Building prototypes and internal utilities

    Finding Specific Things

    For a quick reference on where to find specific content, tools, or documentation, see Finding Things.