                                                                                                         
▗ ▗   ▖ ▖  Claude Code v2.1.25                                                                           
           Opus 4.5 · Claude Max                                                                         
  ▘▘ ▝▝    ~/temp-PRODVERCEL/485/kush/trace                                                              
                                                                                                         
❯ /clear                                                                                                 
  ⎿  (no content)                                                                                        
                                                                                                         
❯  our graph viz (and overall modal concepts) should allow the concept of a group of nodes yes?          
  │                                                                                                      
  │   e.g. a group effectively formed by their link to a full page (or sub section), or maybe a test     
  │                                                                                                      
  │   (say if e2e hten most likely also a user story, or maybe epic\joruney) yes? For our technical      
  │                                                                                                      
  │   view, one aspect of this is more architecutral technical (what swes write beforehand but isnt      
  a     │                                                                                                
  │    diret transaltion of code, but others like uml are direct maps, where possible when the git       
  │                                                                                                      
  │   repo is attached we want to be able to idnex and map the codebase inf ull for aspects lik this     
  │                                                                                                      
  │   to populate our datapoints, with sync on commits to main (choosable branch w\ preview\dev and      
  │                                                                                                      
  │   other profile controls avail), effectively all concepts of our model must be made more robust      
  │                                                                                                      
  │   code views made into a literal graph map of code, cross-linked even by seperate                    
  langs\codebases     │                                                                                  
  │    such that you can see effectively hub-and-spoke like between this different projects\modules,     
  │                                                                                                      
  │   with an indication of how they interact too (e.g. grpc\real rest apis, embedded                    
  │                                                                                                      
  │   function\objects etc), nodes themselves should be as big as projects and as small as               
  individual     │                                                                                       
  │    functions (which on open allow viewing underlying logic and params), this means everything in     
  │                                                                                                      
  │   betewen must be also modeled, this means node details modals (when still in grph page) and the     
  │                                                                                                      
  │   nodde details page must be highly detailed about its "parents" and ancestors int hat regard.       
  │                                                                                                      
  │   Back to the other general views the main idea regarding groups would be that one can tehn          
  │                                                                                                      
  │   identify a gorup of nodes are for a specific very high level user journey or other item. Some      
  │                                                                                                      
  │   of joruneys must be caluclated\dervied by us automatically and not made by the user.               
  │                                                                                                      
  ╰────────────────────────────────────────────────────────────────────────────────────                  
                                                                                                         
⏺ This is a comprehensive vision for enhancing the graph visualization with hierarchical grouping, code  
  mapping, and automatic journey derivation. Let me explore the current implementation to understand what
   foundation exists before we plan the enhancements.                                                    
                                                                                                         
⏺ Explore(Explore graph viz implementation)                                                              
  ⎿  Done (29 tool uses · 109.4k tokens · 2m 5s)                                                         
                                                                                                         
⏺ Excellent. The exploration reveals a sophisticated foundation that's well-designed for your vision.    
  Here's what already exists and what needs to be built:                                                 
                                                                                                         
  Current Foundation (Already Implemented)                                                               
                                                                                                         
  - 7 perspectives with filtering (product, business, technical, ui, security, performance, all)         
  - Aggregation system with type-based grouping, community detection, and shared relationship detection  
  - Entity hierarchy supporting 7+ depth levels with parent-child relationships                          
  - 33+ item types across requirements, technical, UI, and testing domains                               
  - 6 link types (implements, tests, depends_on, related_to, blocks, parent_of)                          
  - GitHub OAuth integration (repo listing, but no code indexing yet)                                    
  - 8 layout algorithms via ELK.js                                                                       
                                                                                                         
  Gaps to Fill for Your Vision                                                                           
                                                                                                         
  1. Code-level entities (file, function, class, method, variable)                                       
  2. Code repository indexing with AST parsing and commit sync                                           
  3. Cross-project/cross-language linking                                                                
  4. Automatic journey derivation via graph traversal                                                    
  5. Enhanced link-based grouping patterns                                                               
                                                                                                         
  This is a significant multi-phase enhancement. Would you like me to enter plan mode to design a        
  comprehensive implementation strategy covering:                                                        
                                                                                                         
  1. Data model extensions (new entity types, link semantics)                                            
  2. Code indexing architecture (parser, sync engine, storage)                                           
  3. Enhanced grouping algorithms (link patterns, journey detection)                                     
  4. Cross-project visualization (multi-repo graph, language indicators)                                 
  5. UI/UX for hierarchical navigation (project→function drill-down)                                     
                                                                                                         
⏺ Entered plan mode                                                                                      
  Claude is now exploring and designing an implementation approach.                                      
                                                                                                         
⏺ I'm now in plan mode. Before designing the implementation, I need to clarify a few key decisions that  
  will shape the architecture.                                                                           
                                                                                                         
⏺ User answered Claude's questions:                                                                      
  ⎿  · What is the primary use case driving this enhancement - tracing code to requirements, or          
     visualizing code architecture itself? → Both Equally                                                
     · Which code repository parsing approach do you prefer for extracting functions/classes? → All \    
      Best of All                                                                                        
     · For automatic journey derivation, what types of patterns should be detected? → All of Above       
     · What should happen when a commit is pushed to the tracked branch? → Incremental Diff              
                                                                                                         
⏺ Understood - comprehensive bidirectional traceability with intelligent multi-strategy parsing, all     
  journey types, and incremental sync. Let me launch parallel plan agents to design each major subsystem.
                                                                                                         
⏺ 3 Plan agents finished (ctrl+o to expand)                                                              
   ├─ Design code indexing architecture · 29 tool uses · 124.3k tokens                                   
   │  ⎿  Done                                                                                            
   ├─ Design graph grouping/hierarchy · 16 tool uses · 106.5k tokens                                     
   │  ⎿  Done                                                                                            
   └─ Design journey derivation · 23 tool uses · 128.0k tokens                                           
      ⎿  Done                                                                                            
                                                                                                         
⏺ Excellent. I now have comprehensive architecture designs from all three planning agents. Let me        
  synthesize these into a cohesive implementation plan.                                                  
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ I've synthesized the comprehensive architecture designs into a cohesive 10-week implementation plan    
  covering:                                                                                              
                                                                                                         
  Key Deliverables:                                                                                      
  1. Code Indexing Service - Tree-sitter + LSP parsing with incremental sync on commits                  
  2. Enhanced Grouping - 4 new algorithms (link targets, dependencies, path hierarchy, semantic patterns)
  3. Hierarchy Navigation - Project→function drill-down with breadcrumb                                  
  4. Cross-Project Visualization - Hub-and-spoke layout with connection type indicators                  
  5. Journey Derivation - Automatic detection of user flows, data paths, and call chains                 
  6. Performance - Virtual rendering, Web Workers, spatial indexing for large graphs                     
                                                                                                         
  The plan leverages your existing infrastructure (aggregation system, entity hierarchy, GitHub OAuth)   
  while adding the new capabilities you described.                                                       
  ⎿ Tool use rejected with user message: Each View is a "dimension" of hte product which itself is a     
    software project\application of sorts, all the various "views" (user facing with our description of  
    what a user wants, e.g. task planner, ability to add and manage tasks, the technical\functional      
    versions of this, whether nodes translate directly or messily via relationships to that form (thisis 
    why nodes are inherently seperate items across views that can then be euqated and maybe viewed as the
     same as a node in another view based on that rel), and then API, Business facing views and          
    constraint mgmt handlings, as well as other items such as our UI\UX both as a lib an das a map\tree  
    of our application interfaces, and tehn views like that of security\perf and many many others, docs  
    is also importnat, as part of codebase idexign you will encounter countless random md docs, as well  
    as probably formal docs \wiki etc, these should be linked into the codde and by def athe other view  
    node item entities too yes? go even more robust and comprehnsive and evalute, we are effectively     
    tying together mind maps of many iffernet dimensions into one unified traceable modal                
                                                                                                         
                                                                                                         
⏺ I understand - this is a much more profound concept than just code mapping. You're describing a        
  multi-dimensional traceability model where:                                                            
                                                                                                         
  1. Each View is a complete dimension - not just a filter, but a full representation of the product from
   that perspective                                                                                      
  2. Nodes exist independently in each view - a "User Login" feature in the user view is a separate      
  entity from "AuthService.login()" in the code view, but they're linked as equivalents                  
  3. Documentation is a first-class dimension - markdown docs, wikis, comments all become nodes linked to
   code and requirements                                                                                 
  4. The unified model = mind maps of many dimensions connected through traceability relationships       
                                                                                                         
  Let me ask some clarifying questions to ensure the architecture captures this correctly:               
                                                                                                         
⏺ User answered Claude's questions:                                                                      
  ⎿  · When the same concept exists in multiple views (e.g., 'Login' in user view, 'AuthService' in      
     code view, 'Security Requirement' in security view), how should equivalence be modeled? → All       
     Three Layers                                                                                        
     · For documentation indexing, what granularity should doc content become nodes? → All Levels        
     · How should the UI present these multi-dimensional views to users? → All + Unified                 
     · What's the relationship between your existing 7 perspectives (product, business, technical,       
     etc.) and these 'dimensions'? → Research codebase to idnetify and maek your own best judgments      
     based on thoguhts & web reearch, review ALL and cosnider hybrids.                                   
                                                                                                         
⏺ Understood - you want the most comprehensive approach:                                                 
  - All Three Layers for equivalence (canonical + projections + inference + manual)                      
  - Hierarchical docs (document → section → chunk)                                                       
  - Unified view with dimension filters                                                                  
  - Research-based decision on perspectives vs dimensions                                                
                                                                                                         
  Let me research the current perspective system and explore best practices for multi-dimensional        
  traceability models.                                                                                   
                                                                                                         
⏺ Explore(Research perspective system)                                                                   
  ⎿  Done (24 tool uses · 86.1k tokens · 1m 21s)                                                         
                                                                                                         
⏺ Web Search("multi-dimensional traceability model software requirements UML canonical node              
            cross-reference architecture 2024 2025")                                                     
  ⎿  Did 1 search in 26s                                                                                 
                                                                                                         
⏺ Excellent research findings. Based on the codebase analysis and industry practices, I can now design a 
  comprehensive multi-dimensional traceability architecture. Let me update the plan with a significantly 
  expanded scope.                                                                                        
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ The plan is now comprehensive, covering:                                                               
                                                                                                         
  Core Conceptual Architecture:                                                                          
  - Three-Layer Equivalence Model: Canonical concepts → View projections → Inferred equivalence          
  - Dimension Orthogonality: Perspectives (WHO sees it) vs Dimensions (WHAT state it's in)               
  - Documentation as First-Class Nodes: Hierarchical document → section → chunk                          
  - Multi-Strategy Equivalence Engine: Annotations, API contracts, naming patterns, semantic similarity  
                                                                                                         
  Key UI Innovations:                                                                                    
  - Five Display Modes: Single, Split, Layered, Unified, Pivot                                           
  - Pivot Navigation: Click a node, see its projections in all perspectives with confidence scores       
  - Dimension Filters: Filter/highlight/color by maturity, complexity, coverage                          
                                                                                                         
  12-Week Implementation Plan with clear phases from foundation through performance optimization.        
  ⎿ Tool use rejected with user message: i dont see where UI views come into play, whether thats the ui  
    tree (page->indiv element decompsition, and ui component library view in general, there has been much
     discussion on this layer prior but it was naive imho) further research please                       
                                                                                                         
⏺ You're right - the UI dimension needs deeper treatment. Let me research the existing UI view           
  implementation and design a comprehensive UI layer.                                                    
                                                                                                         
⏺ Explore(Research UI views and hierarchy)                                                               
  ⎿  Done (28 tool uses · 101.6k tokens · 2m 5s)                                                         
                                                                                                         
⏺ Web Search("design system component library traceability UI component hierarchy graph visualization    
            Storybook Figma integration 2024")                                                           
  ⎿  Did 1 search in 26s                                                                                 
                                                                                                         
⏺ Excellent research. The current codebase has good UI foundations (UIComponentTree, PageInteractionFlow,
   ThumbnailPreview with versioning) but needs elevation to a full dimension. Let me add a comprehensive 
  UI Dimension section to the plan.                                                                      
                                                                                                         
⏺ Read 1 file (ctrl+o to expand)                                                                         
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ Updated plan                                                                                           
  ⎿  /plan to preview                                                                                    
                                                                                                         
⏺ The plan now includes a comprehensive UI Dimension section covering:                                   
                                                                                                         
  1. Page → Element Decomposition (8 depth levels: site → page → layout → section → component → element) 
  2. Component Library Structure (foundations/tokens → primitives → compounds → patterns)                
  3. UI Entity Types (enhanced taxonomy with page templates, section types, route info)                  
  4. Design System Integration (Figma, Storybook, design tokens)                                         
  5. UI-to-Code Traceability (component → implementation → API → backend chain)                          
  6. New Link Types for UI relationships (renders, uses_component, navigates_to, styled_by)              
  7. Database Schema for component libraries and usage tracking                                          
  8. Implementation Phase 8 dedicated to UI dimension                                                    
                                                                                                         
─────────────────────────────────────────────────────────────────────────────────────────────────────────
 Ready to code?                                                                                          
                                                                                                         
 Here is Claude's plan:                                                                                  
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
 Multi-Dimensional Traceability Model: Unified Graph Visualization                                       
                                                                                                         
 Vision                                                                                                  
                                                                                                         
 Transform the graph visualization into a multi-dimensional traceability model that unifies:             
 - Perspectives (stakeholder views: product, business, technical, security, etc.)                        
 - Dimensions (orthogonal cross-cutting concerns: maturity, complexity, coverage)                        
 - Canonical Concepts (abstract entities that manifest as projections in each view)                      
 - Code Mapping (repository indexing with AST-level granularity)                                         
 - Documentation Nodes (hierarchical: document → section → chunk)                                        
 - Automatic Journey Derivation (user flows, data paths, call chains)                                    
                                                                                                         
 The core insight: Each view is a complete dimension of the product, with nodes existing independently   
 per view but linked as equivalents through canonical concepts.                                          
                                                                                                         
 ---                                                                                                     
 Part 1: Conceptual Architecture                                                                         
                                                                                                         
 1.1 Three-Layer Equivalence Model                                                                       
                                                                                                         
 ┌─────────────────────────────────────────────────────────────────────┐                                 
 │                      CANONICAL LAYER                                │                                 
 │  Abstract concepts that exist independently of any view             │                                 
 │  e.g., "User Authentication" concept                                │                                 
 └────────────────────────────┬────────────────────────────────────────┘                                 
                              │ manifests_as                                                             
         ┌────────────────────┼────────────────────┐                                                     
         ▼                    ▼                    ▼                                                     
 ┌───────────────┐   ┌───────────────┐   ┌───────────────┐                                               
 │ PRODUCT VIEW  │   │ TECHNICAL VIEW│   │ SECURITY VIEW │                                               
 │ "Login Feature"│   │ "AuthService" │   │ "Auth Req 2.1"│                                              
 │               │   │ "login()"     │   │               │                                               
 └───────────────┘   └───────────────┘   └───────────────┘                                               
         │                    │                    │                                                     
         └────────────────────┴────────────────────┘                                                     
                     equivalent_to (inferred + manual)                                                   
                                                                                                         
 Three Layers:                                                                                           
 1. Canonical Concepts - Abstract, view-agnostic entities (stored)                                       
 2. View Projections - Concrete nodes in each perspective (stored, linked to canonical)                  
 3. Inferred Equivalence - Auto-detected relationships + manual overrides                                
                                                                                                         
 1.2 Dimension Orthogonality                                                                             
                                                                                                         
                      PERSPECTIVES (Stakeholder Views)                                                   
                      ─────────────────────────────────►                                                 
                      Product │ Technical │ Security │ ...                                               
               ┌──────────────┼───────────┼──────────┤                                                   
               │              │           │          │                                                   
   DIMENSIONS  │  Draft       │     ●     │    ●     │                                                   
   (Cross-     ├──────────────┼───────────┼──────────┤                                                   
   cutting)    │  In Review   │     ●     │          │                                                   
               ├──────────────┼───────────┼──────────┤                                                   
       │       │  Approved    │           │    ●     │                                                   
       ▼       └──────────────┴───────────┴──────────┘                                                   
                                                                                                         
 Perspectives = WHO sees it (product manager, developer, security auditor)                               
 Dimensions = WHAT state it's in (maturity, complexity, test coverage, priority)                         
                                                                                                         
 Dimensions don't filter visibility - they annotate/color nodes within any perspective.                  
                                                                                                         
 1.3 Documentation as First-Class Nodes                                                                  
                                                                                                         
 ┌─────────────────────────────────────────────────────────────────┐                                     
 │                    DOCUMENTATION DIMENSION                       │                                    
 ├─────────────────────────────────────────────────────────────────┤                                     
 │                                                                 │                                     
 │  ┌─────────────┐                                                │                                     
 │  │ Document    │  README.md, API.md, ARCHITECTURE.md            │                                     
 │  │ (doc_root)  │                                                │                                     
 │  └──────┬──────┘                                                │                                     
 │         │                                                       │                                     
 │  ┌──────┴──────┐                                                │                                     
 │  │ Section     │  "## Authentication", "## API Endpoints"       │                                     
 │  │ (doc_section)                                                │                                     
 │  └──────┬──────┘                                                │                                     
 │         │                                                       │                                     
 │  ┌──────┴──────┐                                                │                                     
 │  │ Chunk       │  Paragraphs, code blocks, tables               │                                     
 │  │ (doc_chunk) │  AI-parsed semantic units                      │                                     
 │  └─────────────┘                                                │                                     
 │                                                                 │                                     
 │  Links: documents → mentions → code entities                    │                                     
 │         documents → describes → requirements                    │                                     
 │         documents → specifies → API endpoints                   │                                     
 └─────────────────────────────────────────────────────────────────┘                                     
                                                                                                         
 ---                                                                                                     
 Part 2: Data Model Extensions                                                                           
                                                                                                         
 2.1 Canonical Concept Entity                                                                            
                                                                                                         
 File: /frontend/packages/types/src/canonical.ts (new)                                                   
                                                                                                         
 export interface CanonicalConcept {                                                                     
   id: string;                                                                                           
   projectId: string;                                                                                    
   name: string;                                                                                         
   description?: string;                                                                                 
                                                                                                         
   // Type classification                                                                                
   conceptType: 'feature' | 'capability' | 'component' | 'domain' | 'integration';                       
                                                                                                         
   // Projections in each perspective                                                                    
   projections: {                                                                                        
     perspectiveId: string;                                                                              
     itemId: string;          // The concrete Item in that view                                          
     confidence: number;      // 0-1, how strongly this maps                                             
     source: 'manual' | 'inferred' | 'canonical';                                                        
   }[];                                                                                                  
                                                                                                         
   // Semantic identity                                                                                  
   keywords: string[];                                                                                   
   embedding?: number[];      // Vector for semantic matching                                            
                                                                                                         
   // Metadata                                                                                           
   createdAt: string;                                                                                    
   updatedAt: string;                                                                                    
   createdBy: 'user' | 'system';                                                                         
 }                                                                                                       
                                                                                                         
 2.2 Extended Item Model                                                                                 
                                                                                                         
 File: /frontend/packages/types/src/item.ts (modified)                                                   
                                                                                                         
 export interface Item {                                                                                 
   // ... existing fields ...                                                                            
   id: string;                                                                                           
   projectId: string;                                                                                    
   title: string;                                                                                        
   description?: string;                                                                                 
   type: string;                                                                                         
   status: ItemStatus;                                                                                   
                                                                                                         
   // NEW: Canonical linkage                                                                             
   canonicalId?: string;              // Links to CanonicalConcept                                       
                                                                                                         
   // NEW: Perspective override                                                                          
   perspectives?: string[];           // Override TYPE_TO_PERSPECTIVE default                            
                                                                                                         
   // NEW: Dimension values (orthogonal to perspective)                                                  
   dimensions?: {                                                                                        
     maturity?: 'draft' | 'review' | 'approved' | 'deprecated';                                          
     complexity?: 'low' | 'medium' | 'high' | 'critical';                                                
     coverage?: number;               // 0-100%                                                          
     priority?: 'p0' | 'p1' | 'p2' | 'p3';                                                               
     [key: string]: unknown;          // Extensible                                                      
   };                                                                                                    
                                                                                                         
   // NEW: For code entities                                                                             
   codeRef?: {                                                                                           
     repositoryId: string;                                                                               
     filePath: string;                                                                                   
     startLine: number;                                                                                  
     endLine: number;                                                                                    
     language: string;                                                                                   
     qualifiedName: string;                                                                              
   };                                                                                                    
                                                                                                         
   // NEW: For documentation entities                                                                    
   docRef?: {                                                                                            
     sourceType: 'markdown' | 'wiki' | 'docstring' | 'comment';                                          
     sourcePath: string;                                                                                 
     headingLevel?: number;           // 1-6 for markdown headers                                        
     parentDocId?: string;            // For hierarchical docs                                           
   };                                                                                                    
                                                                                                         
   // Existing                                                                                           
   metadata?: Record<string, unknown>;                                                                   
   parentId?: string;                                                                                    
   version: number;                                                                                      
   createdAt: string;                                                                                    
   updatedAt: string;                                                                                    
 }                                                                                                       
                                                                                                         
 2.3 Enhanced Link Types                                                                                 
                                                                                                         
 File: /frontend/packages/types/src/link.ts (modified)                                                   
                                                                                                         
 export type LinkType =                                                                                  
   // Existing                                                                                           
   | 'implements' | 'tests' | 'depends_on' | 'related_to' | 'blocks' | 'parent_of'                       
                                                                                                         
   // NEW: Cross-view equivalence                                                                        
   | 'same_as'           // Explicit: "these are the same concept"                                       
   | 'represents'        // "code X represents requirement Y"                                            
   | 'manifests_as'      // Canonical → projection                                                       
                                                                                                         
   // NEW: Documentation                                                                                 
   | 'documents'         // "doc X documents code Y"                                                     
   | 'mentions'          // "doc X mentions concept Y"                                                   
   | 'specifies'         // "doc X specifies API Y"                                                      
                                                                                                         
   // NEW: Code relationships                                                                            
   | 'calls' | 'imports' | 'extends' | 'contains'                                                        
                                                                                                         
   // NEW: Navigation                                                                                    
   | 'navigates_to' | 'opens_modal' | 'triggers_event';                                                  
                                                                                                         
 export interface Link {                                                                                 
   // ... existing fields ...                                                                            
                                                                                                         
   // NEW: Cross-perspective indicator                                                                   
   crossPerspective?: boolean;        // True if source and target are in different perspectives         
                                                                                                         
   // NEW: Equivalence confidence (for same_as, represents links)                                        
   equivalenceConfidence?: number;    // 0-1                                                             
   equivalenceSource?: 'manual' | 'inferred' | 'pattern';                                                
 }                                                                                                       
                                                                                                         
 2.4 Perspective Configuration (Project-Customizable)                                                    
                                                                                                         
 File: /frontend/packages/types/src/perspective.ts (modified)                                            
                                                                                                         
 export interface PerspectiveConfig {                                                                    
   id: string;                                                                                           
   projectId?: string;                // undefined = global default                                      
                                                                                                         
   // Display                                                                                            
   label: string;                                                                                        
   description: string;                                                                                  
   icon: string;                                                                                         
   color: string;                                                                                        
                                                                                                         
   // Type mapping (customizable per project)                                                            
   includeTypes: string[];                                                                               
   excludeTypes?: string[];                                                                              
                                                                                                         
   // Layout preferences                                                                                 
   defaultLayout: 'elk' | 'dagre' | 'cose' | 'breadthfirst';                                             
                                                                                                         
   // NEW: Dimension visibility                                                                          
   visibleDimensions?: string[];      // Which dimensions to show in this perspective                    
                                                                                                         
   // NEW: Cross-perspective settings                                                                    
   showCrossPerspectiveLinks?: boolean;                                                                  
   bridgePerspectives?: string[];     // Other perspectives that commonly link to this one               
 }                                                                                                       
                                                                                                         
 2.5 Database Schema Additions                                                                           
                                                                                                         
 -- Canonical concepts table                                                                             
 CREATE TABLE canonical_concepts (                                                                       
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,                                   
   name VARCHAR(500) NOT NULL,                                                                           
   description TEXT,                                                                                     
   concept_type VARCHAR(50) NOT NULL,                                                                    
   keywords TEXT[],                                                                                      
   embedding VECTOR(1536),            -- For semantic search                                             
   created_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   updated_at TIMESTAMPTZ DEFAULT NOW()                                                                  
 );                                                                                                      
                                                                                                         
 -- Canonical projections (many-to-many: canonical ↔ items)                                              
 CREATE TABLE canonical_projections (                                                                    
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   canonical_id UUID NOT NULL REFERENCES canonical_concepts(id) ON DELETE CASCADE,                       
   item_id UUID NOT NULL REFERENCES items(id) ON DELETE CASCADE,                                         
   perspective_id VARCHAR(50) NOT NULL,                                                                  
   confidence DECIMAL(3,2) NOT NULL DEFAULT 1.0,                                                         
   source VARCHAR(20) NOT NULL DEFAULT 'manual',                                                         
   created_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   UNIQUE(canonical_id, item_id)                                                                         
 );                                                                                                      
                                                                                                         
 -- Documentation entities                                                                               
 CREATE TABLE doc_entities (                                                                             
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   repository_id UUID REFERENCES code_repositories(id),                                                  
   item_id UUID REFERENCES items(id),         -- Links to traceability item                              
                                                                                                         
   source_type VARCHAR(50) NOT NULL,          -- markdown, wiki, docstring, comment                      
   source_path VARCHAR(1000) NOT NULL,                                                                   
   heading_level INTEGER,                                                                                
   parent_doc_id UUID REFERENCES doc_entities(id),                                                       
                                                                                                         
   title VARCHAR(500),                                                                                   
   content TEXT,                                                                                         
   content_hash VARCHAR(64),                                                                             
                                                                                                         
   -- Extracted entities for linking                                                                     
   mentioned_symbols TEXT[],                   -- Code symbols mentioned                                 
   mentioned_concepts TEXT[],                  -- Business terms mentioned                               
                                                                                                         
   created_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   updated_at TIMESTAMPTZ DEFAULT NOW()                                                                  
 );                                                                                                      
                                                                                                         
 -- Code entities (from Part 1 plan, enhanced)                                                           
 CREATE TABLE code_entities (                                                                            
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   repository_id UUID NOT NULL REFERENCES code_repositories(id) ON DELETE CASCADE,                       
   item_id UUID REFERENCES items(id),                                                                    
   canonical_id UUID REFERENCES canonical_concepts(id),  -- NEW: direct canonical link                   
                                                                                                         
   entity_type VARCHAR(50) NOT NULL,                                                                     
   qualified_name VARCHAR(1000) NOT NULL,                                                                
   simple_name VARCHAR(255) NOT NULL,                                                                    
   file_path VARCHAR(1000) NOT NULL,                                                                     
   start_line INTEGER NOT NULL,                                                                          
   end_line INTEGER NOT NULL,                                                                            
   language VARCHAR(50) NOT NULL,                                                                        
                                                                                                         
   signature TEXT,                                                                                       
   documentation TEXT,                         -- Extracted docstring                                    
   visibility VARCHAR(20),                                                                               
                                                                                                         
   content_hash VARCHAR(64),                                                                             
   embedding VECTOR(1536),                     -- For semantic matching                                  
                                                                                                         
   created_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   updated_at TIMESTAMPTZ DEFAULT NOW()                                                                  
 );                                                                                                      
                                                                                                         
 -- Project-specific perspective overrides                                                               
 CREATE TABLE perspective_configs (                                                                      
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,                                   
   perspective_id VARCHAR(50) NOT NULL,                                                                  
                                                                                                         
   config_overrides JSONB NOT NULL DEFAULT '{}',                                                         
   custom_type_mapping JSONB,                  -- type → perspectives[]                                  
                                                                                                         
   created_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   updated_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   UNIQUE(project_id, perspective_id)                                                                    
 );                                                                                                      
                                                                                                         
 ---                                                                                                     
 Part 3: Equivalence Detection System                                                                    
                                                                                                         
 3.1 Multi-Strategy Equivalence Engine                                                                   
                                                                                                         
 Location: /backend/internal/equivalence/                                                                
                                                                                                         
 equivalence/                                                                                            
 ├── engine.go              # Orchestrates all strategies                                                
 ├── strategies/                                                                                         
 │   ├── naming.go          # Pattern-based name matching                                                
 │   ├── semantic.go        # Embedding-based similarity                                                 
 │   ├── structural.go      # Graph structure analysis                                                   
 │   ├── api_contract.go    # Frontend→Backend API matching                                              
 │   └── annotation.go      # Explicit @trace comments                                                   
 ├── confidence.go          # Confidence scoring                                                         
 └── resolver.go            # Conflict resolution                                                        
                                                                                                         
 3.2 Detection Strategies (Ordered by Confidence)                                                        
 ┌─────────────────────┬────────────┬─────────────────────────────────────────────┐                      
 │      Strategy       │ Confidence │                How It Works                 │                      
 ├─────────────────────┼────────────┼─────────────────────────────────────────────┤                      
 │ Explicit Annotation │ 1.0        │ Parse @trace-implements X comments in code  │                      
 ├─────────────────────┼────────────┼─────────────────────────────────────────────┤                      
 │ Manual Link         │ 1.0        │ User-created same_as or represents links    │                      
 ├─────────────────────┼────────────┼─────────────────────────────────────────────┤                      
 │ API Contract        │ 0.9        │ Match frontend fetch URLs to backend routes │                      
 ├─────────────────────┼────────────┼─────────────────────────────────────────────┤                      
 │ Shared Canonical    │ 0.9        │ Items linked to same CanonicalConcept       │                      
 ├─────────────────────┼────────────┼─────────────────────────────────────────────┤                      
 │ Naming Pattern      │ 0.7        │ useGetUser → GetUser → user_story:get_user  │                      
 ├─────────────────────┼────────────┼─────────────────────────────────────────────┤                      
 │ Semantic Similarity │ 0.6        │ Embedding cosine similarity > 0.85          │                      
 ├─────────────────────┼────────────┼─────────────────────────────────────────────┤                      
 │ Structural          │ 0.5        │ Similar graph neighborhoods                 │                      
 └─────────────────────┴────────────┴─────────────────────────────────────────────┘                      
 3.3 Confidence Aggregation                                                                              
                                                                                                         
 function computeEquivalenceConfidence(                                                                  
   signals: EquivalenceSignal[]                                                                          
 ): { confidence: number; source: string } {                                                             
   // Weight by source reliability                                                                       
   const weights = {                                                                                     
     'annotation': 1.0,                                                                                  
     'manual': 1.0,                                                                                      
     'api_contract': 0.9,                                                                                
     'canonical': 0.9,                                                                                   
     'naming': 0.7,                                                                                      
     'semantic': 0.6,                                                                                    
     'structural': 0.5                                                                                   
   };                                                                                                    
                                                                                                         
   // Take highest confidence signal, boost if multiple agree                                            
   const sorted = signals.sort((a, b) =>                                                                 
     weights[b.source] * b.confidence - weights[a.source] * a.confidence                                 
   );                                                                                                    
                                                                                                         
   const primary = sorted[0];                                                                            
   const agreementBoost = signals.length > 1 ? 0.1 : 0;                                                  
                                                                                                         
   return {                                                                                              
     confidence: Math.min(1.0, primary.confidence + agreementBoost),                                     
     source: primary.source                                                                              
   };                                                                                                    
 }                                                                                                       
                                                                                                         
 ---                                                                                                     
 Part 4: Documentation Indexing                                                                          
                                                                                                         
 4.1 Markdown Parser                                                                                     
                                                                                                         
 Location: /backend/internal/docindex/                                                                   
                                                                                                         
 type DocParser struct {                                                                                 
     mdParser  goldmark.Markdown                                                                         
     codeLinker *CodeLinker                                                                              
     conceptExtractor *ConceptExtractor                                                                  
 }                                                                                                       
                                                                                                         
 type ParsedDocument struct {                                                                            
     Path     string                                                                                     
     Title    string                                                                                     
     Sections []ParsedSection                                                                            
     CodeRefs []CodeReference      // Links to code entities                                             
     Concepts []ConceptMention     // Business terms mentioned                                           
 }                                                                                                       
                                                                                                         
 type ParsedSection struct {                                                                             
     ID           string                                                                                 
     HeadingLevel int                                                                                    
     Title        string                                                                                 
     Content      string                                                                                 
     Chunks       []SemanticChunk   // AI-parsed meaningful units                                        
     ParentID     string                                                                                 
     Children     []ParsedSection                                                                        
 }                                                                                                       
                                                                                                         
 type SemanticChunk struct {                                                                             
     ID      string                                                                                      
     Type    string  // paragraph, code_block, table, definition, example                                
     Content string                                                                                      
     CodeRefs []string                                                                                   
 }                                                                                                       
                                                                                                         
 4.2 Document-to-Code Linking                                                                            
                                                                                                         
 type CodeLinker struct {                                                                                
     codeEntities map[string]CodeEntity  // qualified_name → entity                                      
 }                                                                                                       
                                                                                                         
 func (l *CodeLinker) ExtractCodeReferences(content string) []CodeReference {                            
     refs := []CodeReference{}                                                                           
                                                                                                         
     // 1. Inline code: `AuthService.login()`                                                            
     inlineCodePattern := regexp.MustCompile("`([^`]+)`")                                                
                                                                                                         
     // 2. Code blocks with file references                                                              
     codeBlockPattern := regexp.MustCompile("```(\\w+)?\\n([\\s\\S]*?)```")                              
                                                                                                         
     // 3. Explicit links: [AuthService](src/auth/service.ts)                                            
     linkPattern := regexp.MustCompile("\\[([^\\]]+)\\]\\(([^)]+)\\)")                                   
                                                                                                         
     // Match against known code entities                                                                
     for _, match := range inlineCodePattern.FindAllString(content, -1) {                                
         symbol := strings.Trim(match, "`")                                                              
         if entity, ok := l.codeEntities[symbol]; ok {                                                   
             refs = append(refs, CodeReference{                                                          
                 Symbol: symbol,                                                                         
                 EntityID: entity.ID,                                                                    
                 Confidence: 0.9,                                                                        
             })                                                                                          
         }                                                                                               
     }                                                                                                   
                                                                                                         
     return refs                                                                                         
 }                                                                                                       
                                                                                                         
 ---                                                                                                     
 Part 5: UI Dimension - Page Decomposition & Component Library                                           
                                                                                                         
 The UI dimension is a complete perspective representing the application's interface layer, with its own 
  hierarchical decomposition and bidirectional traceability to code, requirements, and design.           
                                                                                                         
 5.1 UI Hierarchy Model (Page → Element Decomposition)                                                   
                                                                                                         
 ┌─────────────────────────────────────────────────────────────────────────────┐                         
 │                         UI DIMENSION HIERARCHY                               │                        
 ├─────────────────────────────────────────────────────────────────────────────┤                         
 │                                                                             │                         
 │  LEVEL 0   ┌─────────────────────────────────────────────────────────────┐  │                         
 │  (Site)    │  APPLICATION / SITE                                         │  │                         
 │            │  "TracerTM Web App"                                          │  │                        
 │            └───────────────────────────┬─────────────────────────────────┘  │                         
 │                                        │                                    │                         
 │  LEVEL 1   ┌──────────┬───────────┬────┴────┬──────────┬─────────────────┐  │                         
 │  (Route)   │ /login   │ /dashboard│ /graph  │ /settings│ /projects/:id   │  │                         
 │            │ (page)   │ (page)    │ (page)  │ (page)   │ (page)          │  │                         
 │            └────┬─────┴─────┬─────┴────┬────┴────┬─────┴────────┬────────┘  │                         
 │                 │           │          │         │              │           │                         
 │  LEVEL 2   ┌────┴───┐  ┌────┴───┐  ┌───┴───┐  ┌──┴──┐      ┌───┴────┐     │                           
 │  (Layout)  │ Auth   │  │ Main   │  │ Graph │  │ Settings │ │ Detail │     │                           
 │            │ Layout │  │ Layout │  │ Layout│  │ Layout   │ │ Layout │     │                           
 │            └────┬───┘  └────┬───┘  └───┬───┘  └────┬─────┘ └────┬───┘     │                           
 │                 │           │          │           │            │          │                          
 │  LEVEL 3   ┌────┴───────────┴────┐  ┌──┴───┐  ┌────┴────┐                  │                          
 │  (Section) │ Hero │ Form │ Footer│  │Canvas│  │ Sidebar │                  │                          
 │            │      │      │       │  │      │  │ Content │                  │                          
 │            └────┬─┴──────┴───────┘  └──┬───┘  └────┬────┘                  │                          
 │                 │                      │           │                        │                         
 │  LEVEL 4-5 ┌────┴──────┐          ┌────┴─────┐ ┌───┴────┐                  │                          
 │ (Component)│ LoginForm │          │ NodePanel│ │ NavMenu│                  │                          
 │            │ SocialAuth│          │ Toolbar  │ │ Profile│                  │                          
 │            └────┬──────┘          └────┬─────┘ └───┬────┘                  │                          
 │                 │                      │           │                        │                         
 │  LEVEL 6-7 ┌────┴──────┐          ┌────┴─────┐ ┌───┴────┐                  │                          
 │  (Element) │ Input     │          │ Button   │ │ Avatar │                  │                          
 │            │ Button    │          │ Icon     │ │ Badge  │                  │                          
 │            │ Checkbox  │          │ Tooltip  │ │ Link   │                  │                          
 │            └───────────┘          └──────────┘ └────────┘                  │                          
 │                                                                             │                         
 └─────────────────────────────────────────────────────────────────────────────┘                         
                                                                                                         
 5.2 UI Entity Types (Enhanced)                                                                          
                                                                                                         
 File: /frontend/packages/types/src/ui-entities.ts (new)                                                 
                                                                                                         
 // UI Entity type taxonomy                                                                              
 export type UIEntityType =                                                                              
   // Application level                                                                                  
   | 'application' | 'site' | 'app_shell'                                                                
                                                                                                         
   // Route/Page level                                                                                   
   | 'page' | 'screen' | 'view' | 'route'                                                                
                                                                                                         
   // Layout level                                                                                       
   | 'layout' | 'template' | 'frame'                                                                     
                                                                                                         
   // Section level (semantic page regions)                                                              
   | 'section' | 'header' | 'footer' | 'sidebar' | 'main'                                                
   | 'hero' | 'nav' | 'content_area' | 'card_grid'                                                       
                                                                                                         
   // Modal/Overlay level                                                                                
   | 'modal' | 'dialog' | 'drawer' | 'popup' | 'toast' | 'tooltip' | 'dropdown'                          
                                                                                                         
   // Component level (reusable)                                                                         
   | 'component' | 'widget' | 'block' | 'pattern'                                                        
                                                                                                         
   // Subcomponent level                                                                                 
   | 'subcomponent' | 'compound_part'                                                                    
                                                                                                         
   // Element level (atomic)                                                                             
   | 'element' | 'atom' | 'primitive';                                                                   
                                                                                                         
 // Page template taxonomy                                                                               
 export type PageTemplate =                                                                              
   | 'landing' | 'dashboard' | 'form' | 'list' | 'detail'                                                
   | 'auth' | 'settings' | 'search' | 'wizard' | 'empty_state';                                          
                                                                                                         
 // Section taxonomy (common page regions)                                                               
 export type SectionType =                                                                               
   | 'hero' | 'navigation' | 'breadcrumb' | 'search_bar'                                                 
   | 'sidebar' | 'content' | 'card_grid' | 'table'                                                       
   | 'form' | 'footer' | 'call_to_action' | 'testimonials';                                              
                                                                                                         
 // UI Item extension                                                                                    
 export interface UIItem extends Item {                                                                  
   uiRef: {                                                                                              
     entityType: UIEntityType;                                                                           
                                                                                                         
     // Hierarchy                                                                                        
     depth: number;               // 0-7                                                                 
     path: string[];              // ["app", "dashboard", "main-layout", "sidebar"]                      
                                                                                                         
     // Page context                                                                                     
     pageTemplate?: PageTemplate;                                                                        
     sectionType?: SectionType;                                                                          
                                                                                                         
     // Route info                                                                                       
     routePath?: string;          // "/projects/:id/views/:viewType"                                     
     routeParams?: string[];      // ["id", "viewType"]                                                  
                                                                                                         
     // Component library reference                                                                      
     libraryRef?: {                                                                                      
       libraryId: string;                                                                                
       componentName: string;     // "Button", "Modal", "DataTable"                                      
       variantName?: string;      // "primary", "destructive"                                            
       storyId?: string;          // Storybook story ID                                                  
     };                                                                                                  
                                                                                                         
     // Design reference                                                                                 
     designRef?: {                                                                                       
       figmaNodeId?: string;                                                                             
       figmaFileKey?: string;                                                                            
       figmaPageName?: string;                                                                           
     };                                                                                                  
                                                                                                         
     // Interaction                                                                                      
     interactions?: {                                                                                    
       navigatesTo?: string[];    // Page IDs                                                            
       opensModal?: string[];     // Modal IDs                                                           
       triggersEvent?: string[];  // Event names                                                         
     };                                                                                                  
                                                                                                         
     // Responsiveness                                                                                   
     deviceVariants?: ('desktop' | 'tablet' | 'mobile')[];                                               
     breakpoints?: Record<string, Partial<UIItem>>;                                                      
   };                                                                                                    
 }                                                                                                       
                                                                                                         
 5.3 Component Library Dimension                                                                         
                                                                                                         
 ┌─────────────────────────────────────────────────────────────────────────────┐                         
 │                       COMPONENT LIBRARY STRUCTURE                            │                        
 ├─────────────────────────────────────────────────────────────────────────────┤                         
 │                                                                             │                         
 │  ┌─────────────────────────────────────────────────────────────────────┐   │                          
 │  │ DESIGN SYSTEM ROOT                                                   │   │                         
 │  │ "@tracertm/ui" or project design system                             │   │                          
 │  └───────────────────────────┬─────────────────────────────────────────┘   │                          
 │                              │                                              │                         
 │  ┌───────────────────────────┼───────────────────────────────────────┐     │                          
 │  │                           │                                        │     │                         
 │  ▼                           ▼                                        ▼     │                         
 │  ┌──────────────┐   ┌──────────────┐                      ┌──────────────┐ │                          
 │  │ FOUNDATIONS  │   │ COMPONENTS   │                      │ PATTERNS     │ │                          
 │  │ (Tokens)     │   │ (UI Lib)     │                      │ (Templates)  │ │                          
 │  └──────┬───────┘   └──────┬───────┘                      └──────┬───────┘ │                          
 │         │                  │                                      │         │                         
 │  ┌──────┴─────────┐  ┌─────┴────────────────────────┐    ┌───────┴──────┐  │                          
 │  │ Colors        │  │ Primitives    │ Compounds     │    │ Page         │  │                          
 │  │ Typography    │  │ ───────────   │ ─────────     │    │ Templates    │  │                          
 │  │ Spacing       │  │ Button        │ Card          │    │              │  │                          
 │  │ Shadows       │  │ Input         │ Modal         │    │ Dashboard    │  │                          
 │  │ Borders       │  │ Badge         │ DataTable     │    │ Form         │  │                          
 │  │ Icons         │  │ Avatar        │ Sidebar       │    │ List         │  │                          
 │  │ Motion        │  │ Icon          │ Header        │    │ Detail       │  │                          
 │  └───────────────┘  │ Link          │ CommandPalette│    └──────────────┘  │                          
 │                     └───────────────┴───────────────┘                      │                          
 │                                                                             │                         
 │  COMPONENT METADATA:                                                        │                         
 │  ─────────────────                                                          │                         
 │  • Storybook: storybook.tracertm.dev/docs/components-button--docs          │                          
 │  • Figma: figma.com/file/xxx/Design-System?node-id=123:456                 │                          
 │  • Source: /frontend/packages/ui/src/components/button.tsx                 │                          
 │  • Props: variant, size, disabled, loading, leftIcon, rightIcon            │                          
 │  • Variants: default, primary, secondary, destructive, ghost, link         │                          
 │  • Usage Count: 847 instances across 23 pages                              │                          
 │                                                                             │                         
 └─────────────────────────────────────────────────────────────────────────────┘                         
                                                                                                         
 5.4 Component Library Entity                                                                            
                                                                                                         
 // File: /frontend/packages/types/src/component-library.ts (new)                                        
                                                                                                         
 export interface ComponentLibrary {                                                                     
   id: string;                                                                                           
   projectId: string;                                                                                    
   name: string;                     // "@tracertm/ui"                                                   
   description?: string;                                                                                 
                                                                                                         
   // Source references                                                                                  
   packagePath?: string;             // "frontend/packages/ui"                                           
   storybookUrl?: string;            // "https://storybook.tracertm.dev"                                 
   figmaFileKey?: string;            // Figma file containing the design system                          
                                                                                                         
   // Version tracking                                                                                   
   version: string;                                                                                      
   publishedAt?: string;                                                                                 
                                                                                                         
   metadata?: Record<string, unknown>;                                                                   
 }                                                                                                       
                                                                                                         
 export interface LibraryComponent {                                                                     
   id: string;                                                                                           
   libraryId: string;                                                                                    
                                                                                                         
   // Identity                                                                                           
   name: string;                     // "Button"                                                         
   displayName: string;              // "Button"                                                         
   category: ComponentCategory;                                                                          
                                                                                                         
   // Location                                                                                           
   sourcePath: string;               // "src/components/button.tsx"                                      
   exportName: string;               // "Button" or "default"                                            
                                                                                                         
   // Documentation                                                                                      
   description?: string;                                                                                 
   storyId?: string;                 // "components-button--docs"                                        
   figmaNodeId?: string;                                                                                 
   docUrl?: string;                                                                                      
                                                                                                         
   // Schema                                                                                             
   propsSchema?: PropSchema[];                                                                           
   variants?: ComponentVariant[];                                                                        
   slots?: ComponentSlot[];                                                                              
                                                                                                         
   // Usage metrics                                                                                      
   usageCount: number;                                                                                   
   usedInPages: string[];            // Page IDs using this component                                    
   dependsOn: string[];              // Other component IDs                                              
   dependedOnBy: string[];                                                                               
                                                                                                         
   // Status                                                                                             
   status: 'stable' | 'beta' | 'deprecated' | 'experimental';                                            
   deprecationMessage?: string;                                                                          
   replacedBy?: string;              // Component ID of replacement                                      
                                                                                                         
   createdAt: string;                                                                                    
   updatedAt: string;                                                                                    
 }                                                                                                       
                                                                                                         
 export type ComponentCategory =                                                                         
   | 'primitives'      // Button, Input, Badge                                                           
   | 'forms'           // Form, Field, Select                                                            
   | 'layout'          // Container, Grid, Stack                                                         
   | 'navigation'      // Nav, Breadcrumb, Tabs                                                          
   | 'feedback'        // Alert, Toast, Progress                                                         
   | 'overlays'        // Modal, Drawer, Popover                                                         
   | 'data-display'    // Table, List, Card                                                              
   | 'utilities';      // Portal, VisuallyHidden                                                         
                                                                                                         
 export interface ComponentVariant {                                                                     
   name: string;                     // "primary", "destructive"                                         
   propsOverride: Record<string, unknown>;                                                               
   preview?: {                                                                                           
     screenshotUrl?: string;                                                                             
     storyId?: string;                                                                                   
   };                                                                                                    
 }                                                                                                       
                                                                                                         
 export interface PropSchema {                                                                           
   name: string;                                                                                         
   type: string;                     // "string", "boolean", "ReactNode"                                 
   required: boolean;                                                                                    
   defaultValue?: unknown;                                                                               
   description?: string;                                                                                 
   enumValues?: string[];            // For union types                                                  
 }                                                                                                       
                                                                                                         
 5.5 UI-to-Code Traceability Links                                                                       
                                                                                                         
 ┌─────────────────────────────────────────────────────────────────────────────┐                         
 │                     UI-TO-CODE TRACEABILITY                                  │                        
 ├─────────────────────────────────────────────────────────────────────────────┤                         
 │                                                                             │                         
 │  UI DIMENSION                         CODE DIMENSION                        │                         
 │  ────────────                         ──────────────                        │                         
 │                                                                             │                         
 │  ┌───────────────┐                    ┌───────────────────────────────────┐│                          
 │  │ LoginPage     │───implements───────▶│ src/pages/auth/login.tsx         ││                          
 │  │ (page)        │                    │ LoginPage component               ││                          
 │  └───────┬───────┘                    └───────────────────────────────────┘│                          
 │          │                                                                  │                         
 │          │ contains                                                         │                         
 │          ▼                                                                  │                         
 │  ┌───────────────┐                    ┌───────────────────────────────────┐│                          
 │  │ LoginForm     │───implements───────▶│ src/components/auth/LoginForm.tsx││                          
 │  │ (component)   │                    │ LoginForm component               ││                          
 │  └───────┬───────┘                    └───────────────────────────────────┘│                          
 │          │                                       │                          │                         
 │          │ uses                                  │ imports                  │                         
 │          ▼                                       ▼                          │                         
 │  ┌───────────────┐                    ┌───────────────────────────────────┐│                          
 │  │ Button        │◀───implements──────│ @tracertm/ui/button.tsx           ││                          
 │  │ (lib component)                    │ Button component                  ││                          
 │  └───────────────┘                    └───────────────────────────────────┘│                          
 │          │                                       │                          │                         
 │          │                                       │ calls                    │                         
 │          │                                       ▼                          │                         
 │          │                            ┌───────────────────────────────────┐│                          
 │          │                            │ src/api/auth.ts                   ││                          
 │          └────────────uses_api────────▶│ login() function                 ││                          
 │                                       └───────────────────────────────────┘│                          
 │                                                  │                          │                         
 │                                                  │ calls                    │                         
 │                                                  ▼                          │                         
 │  ┌───────────────┐                    ┌───────────────────────────────────┐│                          
 │  │ User Story    │◀───implements──────│ POST /api/v1/auth/login           ││                          
 │  │ "Login Flow"  │                    │ Backend handler                   ││                          
 │  │ (product view)│                    └───────────────────────────────────┘│                          
 │  └───────────────┘                                                          │                         
 │                                                                             │                         
 └─────────────────────────────────────────────────────────────────────────────┘                         
                                                                                                         
 5.6 UI Link Types                                                                                       
                                                                                                         
 // Additional link types for UI dimension                                                               
 export type UILinkType =                                                                                
   | 'renders'           // Component A renders Component B                                              
   | 'uses_component'    // Page uses a library component                                                
   | 'layout_contains'   // Layout contains section/component                                            
   | 'navigates_to'      // UI element navigates to page                                                 
   | 'opens_modal'       // UI element opens modal                                                       
   | 'triggers_event'    // UI interaction triggers event                                                
   | 'styled_by'         // Component uses design token                                                  
   | 'variant_of'        // Component variant of base                                                    
   | 'deprecated_by'     // Old component deprecated by new                                              
   | 'designed_in'       // UI references Figma design                                                   
   | 'documented_in';    // UI documented in Storybook story                                             
                                                                                                         
 5.7 Design System Integration                                                                           
                                                                                                         
 // Design token reference                                                                               
 export interface DesignTokenRef {                                                                       
   tokenType: 'color' | 'typography' | 'spacing' | 'shadow' | 'border' | 'motion';                       
   tokenPath: string;              // "colors.primary.500"                                               
   resolvedValue?: string;         // "#3b82f6"                                                          
   figmaStyleId?: string;                                                                                
 }                                                                                                       
                                                                                                         
 // Figma integration                                                                                    
 export interface FigmaIntegration {                                                                     
   fileKey: string;                                                                                      
   pageName?: string;                                                                                    
   nodeId?: string;                                                                                      
   lastSyncedAt?: string;                                                                                
   syncStatus: 'synced' | 'outdated' | 'unlinked';                                                       
 }                                                                                                       
                                                                                                         
 // Storybook integration                                                                                
 export interface StorybookIntegration {                                                                 
   storyId: string;                // "components-button--primary"                                       
   storyUrl?: string;                                                                                    
   lastBuildAt?: string;                                                                                 
   hasVisualTests: boolean;                                                                              
   visualTestStatus?: 'passed' | 'failed' | 'pending';                                                   
 }                                                                                                       
                                                                                                         
 5.8 UI Dimension Database Schema                                                                        
                                                                                                         
 -- Component libraries                                                                                  
 CREATE TABLE component_libraries (                                                                      
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   project_id UUID NOT NULL REFERENCES projects(id) ON DELETE CASCADE,                                   
                                                                                                         
   name VARCHAR(255) NOT NULL,                                                                           
   description TEXT,                                                                                     
   package_path VARCHAR(500),                                                                            
   storybook_url VARCHAR(500),                                                                           
   figma_file_key VARCHAR(100),                                                                          
                                                                                                         
   version VARCHAR(50),                                                                                  
   published_at TIMESTAMPTZ,                                                                             
                                                                                                         
   metadata JSONB DEFAULT '{}',                                                                          
   created_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   updated_at TIMESTAMPTZ DEFAULT NOW()                                                                  
 );                                                                                                      
                                                                                                         
 -- Library components                                                                                   
 CREATE TABLE library_components (                                                                       
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   library_id UUID NOT NULL REFERENCES component_libraries(id) ON DELETE CASCADE,                        
   item_id UUID REFERENCES items(id),          -- Links to UI dimension item                             
                                                                                                         
   name VARCHAR(255) NOT NULL,                                                                           
   display_name VARCHAR(255),                                                                            
   category VARCHAR(50) NOT NULL,                                                                        
                                                                                                         
   source_path VARCHAR(500),                                                                             
   export_name VARCHAR(255),                                                                             
                                                                                                         
   description TEXT,                                                                                     
   story_id VARCHAR(255),                                                                                
   figma_node_id VARCHAR(100),                                                                           
   doc_url VARCHAR(500),                                                                                 
                                                                                                         
   props_schema JSONB,                                                                                   
   variants JSONB,                                                                                       
   slots JSONB,                                                                                          
                                                                                                         
   usage_count INTEGER DEFAULT 0,                                                                        
   status VARCHAR(20) DEFAULT 'stable',                                                                  
   deprecation_message TEXT,                                                                             
   replaced_by UUID REFERENCES library_components(id),                                                   
                                                                                                         
   created_at TIMESTAMPTZ DEFAULT NOW(),                                                                 
   updated_at TIMESTAMPTZ DEFAULT NOW()                                                                  
 );                                                                                                      
                                                                                                         
 -- Component usage tracking                                                                             
 CREATE TABLE component_usage (                                                                          
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   component_id UUID NOT NULL REFERENCES library_components(id) ON DELETE CASCADE,                       
                                                                                                         
   page_item_id UUID REFERENCES items(id),     -- Which page uses it                                     
   file_path VARCHAR(500),                      -- Source file using it                                  
   line_number INTEGER,                                                                                  
   usage_context VARCHAR(100),                  -- e.g., "form-field", "navigation"                      
                                                                                                         
   props_used JSONB,                            -- Which props are passed                                
   variant_used VARCHAR(100),                                                                            
                                                                                                         
   created_at TIMESTAMPTZ DEFAULT NOW()                                                                  
 );                                                                                                      
                                                                                                         
 -- Design token references                                                                              
 CREATE TABLE design_token_refs (                                                                        
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   component_id UUID REFERENCES library_components(id) ON DELETE CASCADE,                                
   item_id UUID REFERENCES items(id),                                                                    
                                                                                                         
   token_type VARCHAR(50) NOT NULL,                                                                      
   token_path VARCHAR(255) NOT NULL,                                                                     
   resolved_value VARCHAR(255),                                                                          
   figma_style_id VARCHAR(100),                                                                          
                                                                                                         
   created_at TIMESTAMPTZ DEFAULT NOW()                                                                  
 );                                                                                                      
                                                                                                         
 -- Figma sync state                                                                                     
 CREATE TABLE figma_sync_state (                                                                         
   id UUID PRIMARY KEY DEFAULT gen_random_uuid(),                                                        
   item_id UUID REFERENCES items(id),                                                                    
   component_id UUID REFERENCES library_components(id),                                                  
                                                                                                         
   file_key VARCHAR(100) NOT NULL,                                                                       
   page_name VARCHAR(255),                                                                               
   node_id VARCHAR(100),                                                                                 
                                                                                                         
   last_synced_at TIMESTAMPTZ,                                                                           
   sync_status VARCHAR(20) DEFAULT 'unlinked',                                                           
   figma_modified_at TIMESTAMPTZ,                                                                        
                                                                                                         
   UNIQUE(item_id, file_key, node_id)                                                                    
 );                                                                                                      
                                                                                                         
 5.9 UI Dimension Views                                                                                  
                                                                                                         
 Existing Components to Enhance:                                                                         
 - UIComponentTree.tsx → Becomes the primary UI dimension navigator                                      
 - PageInteractionFlow.tsx → User journey visualization within UI                                        
 - ThumbnailPreview.tsx → Screenshot previews with version tracking                                      
                                                                                                         
 New Components:                                                                                         
 ┌──────────────────────────┬───────────────────────────────────────┐                                    
 │        Component         │                Purpose                │                                    
 ├──────────────────────────┼───────────────────────────────────────┤                                    
 │ ComponentLibraryExplorer │ Browse and search component library   │                                    
 ├──────────────────────────┼───────────────────────────────────────┤                                    
 │ PageDecompositionView    │ Hierarchical page → element breakdown │                                    
 ├──────────────────────────┼───────────────────────────────────────┤                                    
 │ DesignTokenBrowser       │ View and link design tokens           │                                    
 ├──────────────────────────┼───────────────────────────────────────┤                                    
 │ FigmaSyncPanel           │ Manage Figma integration status       │                                    
 ├──────────────────────────┼───────────────────────────────────────┤                                    
 │ ComponentUsageMatrix     │ Where is each component used          │                                    
 ├──────────────────────────┼───────────────────────────────────────┤                                    
 │ UICodeTracePanel         │ Show UI → code → requirement chain    │                                    
 └──────────────────────────┴───────────────────────────────────────┘                                    
 ---                                                                                                     
 Part 6: Unified Graph Architecture                                                                      
                                                                                                         
 6.1 Unified Graph View                                                                                  
                                                                                                         
 File: /frontend/apps/web/src/components/graph/UnifiedGraphView.tsx                                      
                                                                                                         
 interface UnifiedGraphViewProps {                                                                       
   projectId: string;                                                                                    
                                                                                                         
   // View controls                                                                                      
   activePerspectives: string[];      // Multiple perspectives visible                                   
   activeDimensions: DimensionFilter[];                                                                  
                                                                                                         
   // Equivalence display                                                                                
   showEquivalences: boolean;                                                                            
   equivalenceMode: 'hide' | 'highlight' | 'merge';                                                      
                                                                                                         
   // Canonical concepts                                                                                 
   showCanonicalLayer: boolean;                                                                          
                                                                                                         
   // Journey overlay                                                                                    
   activeJourney?: DerivedJourney;                                                                       
 }                                                                                                       
                                                                                                         
 5.2 Multi-Perspective Display Modes                                                                     
 ┌─────────┬─────────────────────────────────────────────────────────────┐                               
 │  Mode   │                         Description                         │                               
 ├─────────┼─────────────────────────────────────────────────────────────┤                               
 │ Single  │ One perspective, cross-links hidden                         │                               
 ├─────────┼─────────────────────────────────────────────────────────────┤                               
 │ Split   │ Side-by-side perspectives, equivalences as bridges          │                               
 ├─────────┼─────────────────────────────────────────────────────────────┤                               
 │ Layered │ Perspectives as semi-transparent layers                     │                               
 ├─────────┼─────────────────────────────────────────────────────────────┤                               
 │ Unified │ All perspectives merged, dimension-colored                  │                               
 ├─────────┼─────────────────────────────────────────────────────────────┤                               
 │ Pivot   │ Focus on one node, show its projections in all perspectives │                               
 └─────────┴─────────────────────────────────────────────────────────────┘                               
 5.3 Dimension Filters                                                                                   
                                                                                                         
 File: /frontend/apps/web/src/components/graph/DimensionFilters.tsx                                      
                                                                                                         
 interface DimensionFilter {                                                                             
   dimension: string;           // 'maturity', 'complexity', 'coverage'                                  
   operator: 'eq' | 'neq' | 'gt' | 'lt' | 'in';                                                          
   value: string | number | string[];                                                                    
   displayMode: 'filter' | 'highlight' | 'color';                                                        
 }                                                                                                       
                                                                                                         
 // Example usage:                                                                                       
 const filters: DimensionFilter[] = [                                                                    
   { dimension: 'maturity', operator: 'eq', value: 'approved', displayMode: 'filter' },                  
   { dimension: 'coverage', operator: 'lt', value: 50, displayMode: 'highlight' },                       
   { dimension: 'complexity', operator: 'in', value: ['high', 'critical'], displayMode: 'color' }        
 ];                                                                                                      
                                                                                                         
 5.4 Pivot Navigation                                                                                    
                                                                                                         
 interface PivotNavigationProps {                                                                        
   currentNode: Item;                                                                                    
   equivalentNodes: {                                                                                    
     perspectiveId: string;                                                                              
     item: Item;                                                                                         
     confidence: number;                                                                                 
     source: string;                                                                                     
   }[];                                                                                                  
   onPivot: (perspectiveId: string, itemId: string) => void;                                             
 }                                                                                                       
                                                                                                         
 // UI: When viewing "Login Feature" in Product perspective,                                             
 // show sidebar with:                                                                                   
 // - Technical: "AuthService.login()" [0.95 confidence]                                                 
 // - Security: "SEC-AUTH-001" [0.90 confidence]                                                         
 // - Code: "src/auth/login.ts:42" [1.0 confidence]                                                      
 // Click to pivot to that perspective focused on that node                                              
                                                                                                         
 ---                                                                                                     
 Part 7: Implementation Phases                                                                           
                                                                                                         
 Phase 1: Foundation (Week 1-3)                                                                          
                                                                                                         
 - Add canonical concept types and database tables                                                       
 - Extend Item model with canonicalId, dimensions, codeRef, docRef                                       
 - Add new link types (same_as, represents, manifests_as, documents)                                     
 - Make perspective configs project-customizable                                                         
 - Create database migrations                                                                            
                                                                                                         
 Phase 2: Equivalence Engine (Week 3-5)                                                                  
                                                                                                         
 - Implement naming pattern matcher                                                                      
 - Implement semantic similarity with embeddings                                                         
 - Implement API contract matcher                                                                        
 - Implement annotation parser (@trace-implements)                                                       
 - Build confidence aggregation                                                                          
 - Create equivalence suggestion UI                                                                      
                                                                                                         
 Phase 3: Code Indexing (Week 4-6)                                                                       
                                                                                                         
 - Tree-sitter parser for TS, Go, Python                                                                 
 - Incremental sync with GitHub webhooks                                                                 
 - Cross-language reference resolution                                                                   
 - Code entity → canonical concept linking                                                               
 - LSP integration for call hierarchies                                                                  
                                                                                                         
 Phase 4: Documentation Indexing (Week 5-7)                                                              
                                                                                                         
 - Markdown parser with section extraction                                                               
 - Semantic chunk detection                                                                              
 - Code reference extraction from docs                                                                   
 - Business concept extraction                                                                           
 - Doc → code → requirement linking                                                                      
                                                                                                         
 Phase 5: Multi-Perspective UI (Week 6-8)                                                                
                                                                                                         
 - Unified graph view with perspective layers                                                            
 - Dimension filter controls                                                                             
 - Pivot navigation component                                                                            
 - Equivalence visualization (merge/bridge modes)                                                        
 - Cross-perspective link highlighting                                                                   
                                                                                                         
 Phase 6: Hierarchy & Grouping (Week 7-9)                                                                
                                                                                                         
 - Enhanced grouping algorithms (link targets, dependencies, paths, semantic)                            
 - Hierarchy navigation with breadcrumbs                                                                 
 - Project → repo → module → file → function drill-down                                                  
 - Canonical concept grouping                                                                            
                                                                                                         
 Phase 7: Journey Derivation (Week 8-10)                                                                 
                                                                                                         
 - User navigation flow detection                                                                        
 - Data flow path tracing                                                                                
 - Call chain analysis                                                                                   
 - Journey scoring and ranking                                                                           
 - Journey explorer UI                                                                                   
                                                                                                         
 Phase 8: UI Dimension (Week 9-11)                                                                       
                                                                                                         
 - UI entity types and component library schema                                                          
 - Page decomposition hierarchy (page → element)                                                         
 - Component library indexing from Storybook                                                             
 - Figma integration (Code Connect / plugin sync)                                                        
 - UI → code traceability auto-detection                                                                 
 - Component usage tracking and metrics                                                                  
 - Design token linking                                                                                  
 - PageDecompositionView and ComponentLibraryExplorer components                                         
                                                                                                         
 Phase 9: Performance & Polish (Week 11-14)                                                              
                                                                                                         
 - Virtual rendering for large graphs                                                                    
 - Web Workers for heavy computation                                                                     
 - Caching strategies                                                                                    
 - Cross-perspective search                                                                              
 - Export/import of equivalence mappings                                                                 
 - Storybook visual testing integration                                                                  
                                                                                                         
 ---                                                                                                     
 Critical Files Summary                                                                                  
 Category: Types (Core)                                                                                  
 Files: frontend/packages/types/src/canonical.ts (new), frontend/packages/types/src/item.ts,             
   frontend/packages/types/src/link.ts                                                                   
 ────────────────────────────────────────                                                                
 Category: Types (UI)                                                                                    
 Files: frontend/packages/types/src/ui-entities.ts (new),                                                
   frontend/packages/types/src/component-library.ts (new)                                                
 ────────────────────────────────────────                                                                
 Category: Backend Equivalence                                                                           
 Files: backend/internal/equivalence/engine.go (new), backend/internal/equivalence/strategies/           
 ────────────────────────────────────────                                                                
 Category: Backend Code Index                                                                            
 Files: backend/internal/codeindex/parsers/, backend/internal/codeindex/sync/                            
 ────────────────────────────────────────                                                                
 Category: Backend Doc Index                                                                             
 Files: backend/internal/docindex/parser.go (new), backend/internal/docindex/linker.go                   
 ────────────────────────────────────────                                                                
 Category: Frontend Graph                                                                                
 Files: frontend/apps/web/src/components/graph/UnifiedGraphView.tsx,                                     
   frontend/apps/web/src/components/graph/PerspectiveSelector.tsx                                        
 ────────────────────────────────────────                                                                
 Category: Frontend Dimensions                                                                           
 Files: frontend/apps/web/src/components/graph/DimensionFilters.tsx (new)                                
 ────────────────────────────────────────                                                                
 Category: Frontend Equivalence                                                                          
 Files: frontend/apps/web/src/components/graph/EquivalencePanel.tsx (new),                               
   frontend/apps/web/src/components/graph/PivotNavigation.tsx (new)                                      
 ────────────────────────────────────────                                                                
 Category: Frontend UI Dimension                                                                         
 Files: frontend/apps/web/src/components/graph/UIComponentTree.tsx (enhance),                            
   frontend/apps/web/src/components/graph/PageDecompositionView.tsx (new),                               
   frontend/apps/web/src/components/graph/ComponentLibraryExplorer.tsx (new)                             
 ────────────────────────────────────────                                                                
 Category: Database                                                                                      
 Files: alembic/versions/XXX_canonical_concepts.py, alembic/versions/XXX_doc_entities.py,                
   alembic/versions/XXX_perspective_configs.py, alembic/versions/XXX_component_libraries.py (new)        
 ---                                                                                                     
 Verification Plan                                                                                       
                                                                                                         
 Unit Tests                                                                                              
                                                                                                         
 - Equivalence detection strategies (each with test cases)                                               
 - Documentation parser with sample markdown                                                             
 - Canonical concept CRUD operations                                                                     
 - Dimension filtering logic                                                                             
                                                                                                         
 Integration Tests                                                                                       
                                                                                                         
 - Code indexing: Parse real TS/Go files, verify entities and references                                 
 - Doc indexing: Parse README, verify code links                                                         
 - Equivalence: Create items in multiple perspectives, verify inference                                  
 - Cross-perspective links: Verify visibility rules                                                      
                                                                                                         
 E2E Tests                                                                                               
                                                                                                         
 - Create canonical concept, link items from 3 perspectives                                              
 - Pivot navigation between perspectives                                                                 
 - Dimension filtering with multiple criteria                                                            
 - Journey derivation and overlay                                                                        
 - Page decomposition: Create page with sections and components, verify hierarchy                        
 - Component library: Import from Storybook, verify component catalog                                    
 - UI-to-code tracing: Link UI component to implementation code                                          
                                                                                                         
 Performance Benchmarks                                                                                  
                                                                                                         
 - 100 items across 5 perspectives: <100ms render                                                        
 - 1000 code entities: <500ms equivalence inference                                                      
 - 50 documents: <200ms doc parsing                                                                      
 - Cross-perspective search: <300ms                                                                      
                                                                                                         
 ---                                                                                                     
 Research Sources                                                                                        
                                                                                                         
 Traceability & Requirements:                                                                            
 - https://link.springer.com/article/10.1007/s10796-007-9038-3 - Model conformance traceability          
 - https://ieeexplore.ieee.org/document/7323119/ - ReqIF standardized interchange                        
 - https://mid.de/en/competences/model-based-systems-engineering/ - UML/SysML to requirements to code    
 - https://www.sciencedirect.com/topics/engineering/requirement-traceability - Four orthogonal           
 traceability dimensions in SPL                                                                          
                                                                                                         
 Design System & UI Integration:                                                                         
 - https://help.figma.com/hc/en-us/articles/360045003494-Storybook-and-Figma - Official Figma-Storybook  
 linking                                                                                                 
 - https://www.figma.com/blog/what-we-launched-at-framework-2024/ - Production code snippets in Figma    
 Dev Mode                                                                                                
 - https://story.to.design/blog/from-storybook-to-figma - Sync Storybook components to Figma             
 - https://www.animaapp.com/blog/design-systems/how-to-sync-your-storybook-design-system-into-figma/ -   
 Storybook → Figma sync                                                                                  
 - https://medium.com/comsystoreply/design-code-%EF%B8%8F-how-to-bridge-the-gap-with-figma-and-storybook 
 -41719ff44ade - Bridging design and development                                                         
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
                                                                                                         
 Would you like to proceed?                                                                              
                                                                                                         
 ❯ 1. Yes, clear context and bypass permissions                                                          
   2. Yes, and bypass permissions                                                                        
   3. Yes, manually approve edits                                                                        
   4. Type here to tell Claude what to change                                                            
                                                                                                         
 ctrl-g to edit in VS Code · ~/.claude/plans/eventual-toasting-eich.md                                   

:
