flowwink: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Development (auto-runs migrations before starting)
npm run dev

# Production build
npm run build

# Lint
npm run lint

# Run all tests
npx vitest run

# Run a single test file
npx vitest run src/lib/utils.test.ts

# Run tests in watch mode
npx vitest

# Generate template JSON (after editing templates)
bun run scripts/templates-to-json.ts

# Sync block schema definitions
bun run scripts/sync-block-schema.ts

# Lint skill metadata
bun run scripts/skill-linter.ts

# Scaffold a new module
bun run scripts/new-module.ts

# Verify HR module integrity
npm run verify:hr-modules

# Run MCP regression tests
npm run test:mcp-regression

# Run timesheet regression tests
npm run test:timesheet-regression

# Check doc drift
bun run scripts/check-doc-drift.ts

Architecture

FlowWink is a self-hosted Business Operating System (BOS) built on React + Supabase. An autonomous AI operator called FlowPilot runs content, leads, orders, and growth — around the clock. Each deployment is a single-tenant site for one customer.

Request flow

Visitor → PublicPage.tsx → get-page edge function → page.content_json (ContentBlock[])
                         → BlockRenderer.tsx → [Name]Block.tsx (renders each block)

Admin → PageEditorPage.tsx → BlockEditor.tsx → [Name]BlockEditor.tsx (edit each block)

Pages are stored in the pages table as content_json: ContentBlock[]. PublicPage fetches via the get-page edge function (with DB fallback), then BlockRenderer dispatches to the appropriate block component by block.type.

Core Architecture Principle: Blocks are interfaces to FlowPilot

Blocks have two responsibilities only:

1. Intent capture — structured UI that makes the visitor's intent explicit
2. Response rendering — display FlowPilot's answer in a visual format

FlowPilot is always the intelligence layer. Blocks never build their own AI pipelines.