Savvi Studio

Reference Documentation

Last Updated: April 1, 2026

This directory contains all reference documentation for the Savvi Studio project, organized by topic. Reference documentation is intended to be comprehensive, reusable, and stable across different features and tasks.

Table of Contents

  1. Product Requirements
  2. Graph
  3. Module System
  4. Templates
  5. Storybook Reference
  6. Architecture Reference
  7. Database Reference
  8. Forge Patterns
  9. Contributing

Product Requirements

Central reference point for Savvi Studio product requirements, domain model, and business logic.

Product Requirements Documentation - Domain-specific requirements built on top of the graph infrastructure.

Key Sections:

Purpose:

  • Single source of truth for product direction
  • Keep development aligned with business goals
  • Foundation for technical decisions
  • Clear success criteria and definitions

Graph

Reference documentation for the graph data layer: resource and statement models, permission system, and query patterns.

Graph Architecture Overview

Why a graph model, why PostgreSQL, system primitives, and architecture layers.

Resource Model

Resource table schema, Snowflake IDs, kind classifier, external-id uniqueness, and TypeScript mapping.

Statement Model

Statement (triple) table schema, predicate semantics via ltree, referential integrity, and temporal validity.

Permissions

Bitmask permission encoding, predicate policies, permission cache, SQL functions, and query-layer API.

Cursor Pagination

Cursor-based pagination contract for large result sets.

External Linking

External-ID linking patterns.

Reserved IDs

Reserved resource ID ranges.

Module System

Declarative, composable module manifests for domain modeling.

Module System Overview

Why declarative modules, manifest format, object types, compilation pipeline, install plans, and non-technical authoring.

Key Topics:

  • Module manifest YAML format and object types
  • Module composition via imports and exports
  • Compilation pipeline (YAML → JSON bundle + TypeScript)
  • Install plan and idempotent execution
  • Export surfaces — classifiers vs templates (see Export Surfaces)

Templates

Reusable templates for resource/statement creation and documentation.

Template System Overview

Why templates, expression language, composition, and inferred migrations.

Feature Spec Template

Standard template for feature specifications.

Storybook Reference

Comprehensive guides for Storybook integration, testing, and component documentation.

Story Structure

Standard patterns for story file structure, meta configuration, tags system, lifecycle hooks, and best practices.

Key Topics:

  • Basic story structure
  • Meta configuration and layout options
  • Tags system for organization
  • Lifecycle hooks (beforeEach/afterEach)
  • Story-level overrides
  • Best practices for story organization

Testing Patterns

Testing Library best practices, query selection strategies, and interaction testing patterns.

Key Topics:

  • Testing Library query priority (getByRole, getByLabelText, etc.)
  • Query types (getBy*, queryBy*, findBy*)
  • Play functions and user interactions
  • Step function for organized tests
  • Function spying with fn()
  • Common testing patterns

MSW Handlers

Mock Service Worker (MSW) handler patterns, including type-safe tRPC integration.

Key Topics:

  • MSW-tRPC integration setup and benefits
  • Query and mutation handlers
  • Error handling patterns
  • Advanced patterns (stateful handlers, delays)
  • Best practices for realistic mocking

Decorators

Decorator patterns for wrapping stories with context providers and authentication states.

Key Topics:

  • Authentication decorators (withAuth, withAdmin, withNoAuth)
  • Provider decorators (QueryClient, Theme, Router)
  • Decorator composition and factories
  • Global vs story-level decorators
  • Best practices and common patterns

Helpers

Reusable helper utilities to reduce boilerplate and ensure consistency.

Key Topics:

  • Meta helpers (createStoryMeta)
  • Decorator helpers (withAuth, withAdmin, withNoAuth)
  • Handler helpers (withHandlers)
  • Play function helpers (createPlayFunction)
  • Implementation guide and migration strategy

Architecture Reference

Documentation of system architecture, design patterns, and architectural decisions.

Analysis

Comprehensive analysis of the Savvi Studio architecture, including layer separation, dependency management, and design patterns.

Cursor Stream Architecture

Documentation of the cursor-based streaming architecture for handling large datasets and real-time updates.

MCP Tool Contracts

Declarative contract framework for Studio MCP tools — preconditions, postconditions, semantic types, capability tags, and the tool dependency graph. Includes the execution step schema for closed agent feedback loops.

Database Reference

Database patterns, migration strategies, and formal verification approaches.

Patterns

Common database patterns used throughout the project, including graph database patterns, audit logging, and transaction management.

fp-ts Migration

Guide for migrating database code to use functional programming patterns with fp-ts.

Zod Verification

Formal verification approach using Zod schemas to ensure type safety between PostgreSQL and TypeScript.

Forge Patterns

Documentation organization standards and proven patterns for the Savvi Studio project.

Documentation Organization Pattern

Proven pattern for organizing task-based documentation with centralized reference guides.

Key Topics:

  • Problem: repetition, inconsistency, maintenance burden
  • Solution: centralized reference pattern with modular structure
  • Implementation guide (phases and steps)
  • Success metrics and examples
  • Successfully applied to storybook-integration/ and product-requirements/

When to Use:

  • Organizing large documentation sets
  • Reducing duplication across task files
  • Creating reusable reference guides
  • Improving documentation discoverability

Contributing

Adding New Reference Documentation

  1. Determine the correct category:

    • Storybook: Component documentation and testing
    • Architecture: System design and patterns
    • Database: Data layer patterns and migrations
    • Templates: Reusable document templates

  2. Create the document:

    # Example: Adding a new Storybook reference
touch docs/reference/storybook/new-topic.md

  3. Use consistent structure:

    • Title and last updated date
    • Table of contents
    • Clear sections with examples
    • Related documentation links
    • Best practices section

  4. Update this README:

    • Add link in appropriate section
    • Include brief description
    • List key topics

  5. Update .cursorrules:

    • Add reference to new documentation
    • Update relevant sections

Reference Documentation Guidelines

Reference docs should be:

  • ✅ Comprehensive and detailed
  • ✅ Reusable across multiple tasks
  • ✅ Stable (not frequently changing)
  • ✅ Well-organized with clear sections
  • ✅ Rich with examples and best practices

Reference docs should NOT:

  • ❌ Contain task-specific implementation details
  • ❌ Include temporary or experimental content
  • ❌ Duplicate information across files
  • ❌ Change frequently with each feature

Task Documentation vs Reference Documentation

Task Documentation (docs/[task-folder]/):

  • Specific to a feature or project
  • Includes step-by-step instructions
  • May contain temporary notes
  • Links to reference docs for details

Reference Documentation (docs/reference/):

  • General knowledge and patterns
  • Comprehensive and authoritative
  • Stable and reusable
  • Serves multiple tasks/features

Directory Structure

docs/reference/
├── README.md                          # This file
├── product-requirements/              # Product requirements and domain model
│   ├── README.md                      # Requirements overview
│   ├── 01-domain-model/              # Core entities and relationships
│   ├── 02-business-logic/            # Workflows and rules
│   ├── 03-permissions/               # Access control
│   └── reference/                    # Implementation guides
│       └── templates/                # Documentation templates
├── architecture/
│   ├── analysis.md                    # Architecture analysis
│   └── cursor-stream.md               # Cursor stream architecture
├── auth/                              # Auth system reference (in docs/auth/)
├── database/
│   ├── patterns.md                    # Database patterns
│   ├── fp-ts-migration.md            # fp-ts migration guide
│   └── zod-verification.md           # Zod verification approach
├── forge/                             # Documentation organization patterns
│   └── documentation-organization-pattern.md
├── graph/
│   ├── README.md                      # Graph architecture overview
│   ├── resource-model.md              # Resource table schema
│   ├── statement-model.md             # Statement table schema
│   ├── permissions.md                 # Permission model
│   ├── cursor-pagination.md           # Cursor pagination contract
│   ├── external-linking.md            # External-ID linking
│   └── reserved-ids.md               # Reserved ID ranges
├── storybook/
│   ├── story-structure.md            # Story structure and patterns
│   ├── testing-patterns.md           # Testing Library patterns
│   ├── msw-handlers.md               # MSW handler patterns
│   ├── decorators.md                 # Decorator patterns
│   └── helpers.md                    # Reusable helpers
├── modules/
│   └── README.md                      # Module system overview
└── templates/
    ├── README.md                      # Template system overview
    └── feature-spec.md               # Feature spec template

For questions or suggestions about reference documentation organization, please update this README or discuss in team documentation reviews.