Breadcrumb Implementation

Overview

Every page in the app is represented as a row spanning two tables: a shared blocks table that holds the tree structure, and a page_properties table that holds page-specific columns with real database constraints.

This is the shared skeleton + type tables pattern. The blocks table owns the universal tree shape (id, type, parent, content). Each block type gets its own properties table with proper columns, indexes, and constraints — never a JSON blob.

Breadcrumbs are built by joining blocks with page_properties and walking the parent pointer chain upward. Path lookups hit an indexed UNIQUE column, not json_extract().

Why Table-Per-Type

“Everything is a block” doesn't mean everything goes in one table. The block model defines the tree structure — parent/child relationships. The properties of each type are fundamentally different and deserve their own schema.

With ~15 rows the performance difference is zero. This is a data design decision, not a performance one — we want the DB to enforce correctness so the application layer doesn't have to.

Database Schema

Migration 003-blocks-table.sql — two tables in one migration. The tree lives in blocks, page-specific data lives in page_properties.

CREATE TABLE blocks (
  id          TEXT PRIMARY KEY,  -- crypto.randomUUID()
  type        TEXT NOT NULL,     -- "page" (future: "text", "heading", "image")
  content     TEXT,               -- JSON array of child block IDs
  parent      TEXT,               -- FK → blocks.id (NULL for root)
  created_at  TEXT NOT NULL,
  updated_at  TEXT NOT NULL,

  FOREIGN KEY (parent) REFERENCES blocks(id)
);

CREATE TABLE page_properties (
  block_id     TEXT PRIMARY KEY,  -- FK → blocks.id (1:1)
  path         TEXT UNIQUE NOT NULL, -- "/pool", "/apps"
  title        TEXT NOT NULL,        -- "Pool", "CPU Ladder"
  description  TEXT,               -- OG / meta description
  icon         TEXT,               -- lucide icon name
  hidden       BOOLEAN DEFAULT 0,  -- exclude from nav

  FOREIGN KEY (block_id) REFERENCES blocks(id)
);

Column Reference — blocks

Column Reference — page_properties

Future block types get their own table: text_properties, image_properties, etc. Each with its own shape, constraints, and indexes. No ALTER TABLE on existing tables — just CREATE TABLE.

Page Tree

The complete hierarchy to seed. Each entry creates one row in blocks (type = "page") and one row in page_properties. Dynamic slug pages (/posts/[slug], /docs/[slug]) are not stored — they derive breadcrumbs from their parent section at runtime using the currentTitle prop.

~15 page blocks. Each creates one row in blocks and one in page_properties. The seed script inserts both in a transaction.

Query API

Module: src/modules/blocks/queries.ts — follows the pattern from src/modules/content/queries.ts. Page lookups join blocks with page_properties using an indexed path column — no json_extract().

PageBreadcrumb Component

An async server component in src/components/layout/PageBreadcrumb.tsx. Uses the existing shadcn Breadcrumb primitives from @/components/ui/breadcrumb.

Props

Rendering Logic

• Call getPageByPath(path) to find the current page block (joins blocks + page_properties).
• Call getAncestors(block.id) to get the ancestor chain — returns [root, ..., parent], each with path and title from the joined properties.
• Skip root — the / block is never shown in the breadcrumb trail.
• Render each ancestor (except root) as a BreadcrumbLink pointing to its path.
• Render the current page as a BreadcrumbPage (plain text, not a link).
• If currentTitle is provided, use it as the final crumb label instead of the block's title. The block at path becomes an ancestor link, and currentTitle becomes the current page text.
• Separate crumbs with BreadcrumbSeparator (renders a chevron).

Examples

Route Coverage

Every route in the app and how it receives breadcrumbs.

Implementation Phases

Four phases, done incrementally. Each phase produces a working state.

TypeScript Types

Module: src/modules/blocks/types.ts

PageBlock is the flattened result of joining blocks with page_properties. No JSON.parse() needed — every field is a proper column with a known type. The parseBlock() helper only needs to handle JSON.parse() on content (the child ID array) and the hidden boolean coercion.

File Map

Every file involved — what to create, what to modify, what to reuse.

Verification

Commands and checks to run after each phase, in order.