Use Cases Registry Guide
Learn how the Inverse Pyramid documentation system works and how to manage the Use Case registry.
Overview
The Use Case Registry is a specialized documentation system designed to map technical implementation (code, tests) to business requirements. It uses an Inverse Pyramid model, allowing atomic use cases to be consumed by multiple parents in a Directed Acyclic Graph (DAG) structure.
The Inverse Pyramid Concept
Traditional trees force a single parent. In the Inverse Pyramid, a single "Authentication Validation" use case can be a child of both "Security Infrastructure" and "Login Flows". This prevents duplication and accurately reflects how code is shared across the platform.
Technical Architecture
The system relies on two sources of truth that are kept in sync automatically by Server Actions.
The global index. Used for fast searching, hierarchy traversals, and tracking the next ID (e.g., UC-02315).
The content source. Each use case has its own markdown file containing YAML frontmatter and the detailed description.
Managing Use Cases
Creation
Create use cases via the "Create" button. You can assign parents, paths to packages/apps/tests, and tags. Adding a "Child Use Case" from a detail page automatically links the current case as the parent.
N-ary Relationships
Use the "Move" or "Edit" dialogs to manage relationships. You can add multiple parents to any use case to integrate it into different parts of the platform hierarchy.
Tagging System
Tags allow for cross-cutting categorization (e.g., "Critical", "Authentication", "Phase 1").
- Manage tags globally at
/use-cases/tags. - Tags feature custom colors and background presets.
- Deleting a tag automatically scrubs the ID from all related markdown files and the registry.
CLI & Scripts
Use these scripts to maintain the UC pipeline from the terminal: