@zenuml/core 3.32.6 → 3.32.7

package/docs/CONTEXT-tier2-component.md

@@ -0,0 +1,96 @@
+# [COMPONENT NAME] - Component Context (Tier 2)
+
+> **Note**: This is component-specific context. See root **CLAUDE.md** for master project context and coding standards.
+
+## Purpose
+[Brief description of this component's role in the system. What problem does it solve and how does it fit into the overall architecture?]
+
+## Current Status: [Status Description] ✅/🚧/📋
+[Current implementation state, what's working, what's in progress, and key milestones achieved]
+
+## Component-Specific Development Guidelines
+- **[Technology/Framework]**: [Specific technology requirements for this component]
+- **[Architecture Pattern]**: [Component-specific architectural approach]
+- **[Code Organization]**: [How code should be structured within this component]
+- **[Integration Patterns]**: [How this component integrates with others]
+- **[Quality Standards]**: [Component-specific quality requirements]
+
+## Key Component Structure
+
+### Core Modules (`[path]/`)
+- **[module1]/** - [Purpose and key functionality]
+  - **[file1].[ext]** - [Specific file purpose and key features]
+  - **[file2].[ext]** - [Specific file purpose and key features]
+- **[module2]/** - [Purpose and key functionality]  
+- **[module3]/** - [Purpose and key functionality]
+
+### [Secondary Structure] (`[path]/`)
+- **[component].[ext]** - [Component purpose and architecture pattern]
+- **[utilities].[ext]** - [Utility functions and helpers]
+- **[config].[ext]** - [Configuration and settings management]
+
+### [Integration Layer] (`[path]/`)
+- **[integration1].[ext]** - [External service integration patterns]
+- **[integration2].[ext]** - [Inter-component communication]
+
+## Implementation Highlights
+
+### [Key Feature 1]
+- **[Technical Implementation]**: [How this feature is implemented]
+- **[Architecture Decision]**: [Why this approach was chosen]
+- **[Performance Considerations]**: [Optimization details]
+- **[Integration Points]**: [How it connects to other components]
+
+### [Key Feature 2]  
+- **[Implementation Pattern]**: [Technical implementation approach]
+- **[Quality Measures]**: [Testing, monitoring, error handling]
+- **[Scalability Considerations]**: [How it handles growth/load]
+
+### [Key Feature 3]
+- **[Technical Details]**: [Implementation specifics]
+- **[Dependencies]**: [External dependencies and integration points]
+- **[Configuration]**: [How it's configured and customized]
+
+## Critical Implementation Details
+
+### [Technical Pattern 1]
+**[Pattern Description]**: [What problem this pattern solves]
+
+```[language]
+// Example implementation showing the pattern
+[code example demonstrating the critical implementation]
+```
+
+### [Technical Pattern 2]  
+**[Architecture Decision]**: [Why this approach was chosen]
+
+```[language]
+// Code example showing architecture implementation
+[code example demonstrating the architecture]
+```
+
+### [Integration Pattern]
+**[Integration Description]**: [How this component integrates with others]
+
+```[language]
+// Integration implementation example  
+[code example showing integration patterns]
+```
+
+## Development Notes
+
+### [Current Challenges]
+- **[Challenge 1]**: [Description and current approach]
+- **[Challenge 2]**: [Description and mitigation strategy]
+
+### [Future Considerations]
+- **[Enhancement 1]**: [Planned improvement and rationale]
+- **[Enhancement 2]**: [Future architectural evolution]
+
+### [Performance Metrics]
+- **[Key Metric 1]**: [Current performance and targets]
+- **[Key Metric 2]**: [Monitoring and optimization approach]
+
+---
+
+*This component documentation provides context for AI-assisted development within [COMPONENT NAME]. For system-wide patterns and standards, reference the master CLAUDE.md file.*

package/docs/CONTEXT-tier3-feature.md

@@ -0,0 +1,162 @@
+# [FEATURE NAME] Documentation (Tier 3)
+
+*This file documents [feature/module] patterns, architectural decisions, and implementations within [component name].*
+
+## [Feature] Architecture Overview
+
+### [Architecture Decision Title]
+
+**Context**: [Situation that led to this architectural decision]
+
+**Decision**: [What was decided and implemented]
+
+**Reasoning**:
+- **[Benefit 1]**: [Why this approach provides this benefit]
+- **[Benefit 2]**: [Technical or business advantage]  
+- **[Benefit 3]**: [Performance or maintainability benefit]
+- **[Benefit 4]**: [Developer experience or operational benefit]
+
+**Consequences**:
+- [Positive outcome from this decision]
+- [Technical improvement achieved]
+- [Operational or maintenance benefit]
+- [User experience enhancement]
+
+## [Feature] Implementation Patterns
+
+### [Implementation Pattern 1]
+
+**File Organization**:
+```
+[feature-directory]/
+├── [file1].[ext]      # [Purpose and responsibility]
+├── [file2].[ext]      # [Purpose and responsibility]  
+├── [file3].[ext]      # [Purpose and responsibility]
+└── [file4].[ext]      # [Purpose and responsibility]
+```
+
+**Architecture Benefits**:
+- **[Benefit 1]**: [How this organization provides this benefit]
+- **[Benefit 2]**: [Technical advantage of this structure]
+- **[Benefit 3]**: [Maintainability or scalability benefit]
+- **[Benefit 4]**: [Developer experience improvement]
+
+### [Implementation Pattern 2]
+
+**Architecture Decision**: [Technical approach taken]
+
+**Context**: [Background and requirements that led to this approach]
+
+**Decision**: [Specific implementation choice made]
+
+**Reasoning**:
+- **[Technical Reason]**: [Why this was the best technical choice]
+- **[Performance Reason]**: [Performance benefits]
+- **[Maintainability Reason]**: [Long-term maintenance benefits]
+- **[Integration Reason]**: [How it integrates with other components]
+
+**Implementation Details**:
+```[language]
+// [Description of what this code demonstrates]
+[detailed code example showing the implementation pattern]
+```
+
+### [Implementation Pattern 3]
+
+**[Pattern Name]**: [Description of the pattern]
+
+```[language]
+// [Code example title]
+[comprehensive code example showing the pattern in action]
+```
+
+**Implementation Benefits**:
+- **[Benefit 1]**: [Specific advantage this implementation provides]
+- **[Benefit 2]**: [Performance or reliability improvement]
+- **[Benefit 3]**: [Developer experience enhancement]
+
+## [Technical Domain] Implementation
+
+### [Technical Feature 1]
+
+**[Feature Description]**: [What this feature does and why it's important]
+
+**Architecture Pattern**:
+```[language]
+// [Description of the architectural approach]
+[code example demonstrating the architecture]
+```
+
+**Key Implementation Details**:
+- **[Detail 1]**: [Important implementation consideration]
+- **[Detail 2]**: [Technical constraint or optimization]
+- **[Detail 3]**: [Integration or performance consideration]
+
+### [Technical Feature 2]
+
+**Implementation Approach**: [How this feature is implemented]
+
+```[language]
+// [Code example description]
+[detailed implementation example]
+```
+
+**Technical Considerations**:
+- **[Consideration 1]**: [Important technical factor]
+- **[Consideration 2]**: [Performance or scalability factor]
+- **[Consideration 3]**: [Maintenance or testing consideration]
+
+## [Integration/Communication] Patterns
+
+### [Integration Pattern 1]
+
+**Context**: [When and why this integration pattern is used]
+
+**Implementation**:
+```[language]
+// [Integration example description]
+[code showing integration implementation]
+```
+
+**Benefits**:
+- **[Integration Benefit 1]**: [How this improves system integration]
+- **[Integration Benefit 2]**: [Performance or reliability improvement]
+
+### [Integration Pattern 2]
+
+**Pattern Description**: [What problem this integration pattern solves]
+
+```[language]
+// [Integration code example]
+[implementation showing integration pattern]
+```
+
+## Performance & Optimization Details
+
+### [Performance Optimization 1]
+**Optimization**: [What was optimized and how]
+- **Before**: [Previous performance characteristics]
+- **After**: [Improved performance metrics]
+- **Implementation**: [How the optimization was achieved]
+
+### [Performance Optimization 2]  
+**Technical Improvement**: [Specific performance enhancement]
+- **Impact**: [Measurable improvement achieved]
+- **Method**: [Technical approach used]
+- **Trade-offs**: [Any compromises made for the optimization]
+
+## Error Handling & Edge Cases
+
+### [Error Scenario 1]
+**Scenario**: [What error condition this handles]
+**Handling**: [How the error is detected and managed]
+**Recovery**: [How the system recovers from this error]
+
+### [Error Scenario 2]
+**Edge Case**: [Unusual condition that needs handling]  
+**Solution**: [How the implementation handles this case]
+**Validation**: [How this handling is tested or verified]
+
+---
+
+*This feature documentation provides detailed implementation context for AI-assisted development. For broader component context, see the component-level CONTEXT.md file.*

package/docs/README.md

@@ -0,0 +1,207 @@
+# Documentation System Guide
+
+This guide explains how the 3-tier documentation architecture powers the Claude Code Development Kit and why it provides superior results compared to traditional documentation approaches.
+
+## Critical Foundation Files
+
+Two files form the cornerstone of the entire documentation system:
+
+1. **docs-overview.md** - The central routing guide that directs AI agents to appropriate documentation based on task complexity. This file maps your entire documentation structure and enables intelligent context loading.
+
+2. **project-structure.md** - The comprehensive overview of your project's complete file structure and technology stack. This file is required reading for all AI agents and must be attached to Gemini consultations.
+
+These foundation files ensure AI agents always have the essential context needed to understand your project and navigate to relevant documentation.
+
+## Why the 3-Tier System
+
+### Traditional Documentation Problems
+
+Standard documentation approaches create friction for AI-assisted development:
+
+- **Context Overload** - AI agents must process entire documentation sets for simple tasks
+- **Maintenance Burden** - Every code change cascades to multiple documentation locations
+- **Stale Content** - Documentation diverges from implementation reality
+- **No AI Optimization** - Human-readable formats lack structure for machine processing
+
+### The 3-Tier Solution
+
+The kit solves these problems through hierarchical organization:
+
+**Tier 1: Foundation (Rarely Changes)**
+- Project-wide standards, architecture decisions, technology stack
+- Auto-loads for every AI session
+- Provides consistent baseline without redundancy
+- Uses CLAUDE.md as the master context file
+
+**Tier 2: Component (Occasionally Changes)**
+- Component boundaries, architectural patterns, integration points
+- Loads only when working within specific components
+- Isolates architectural decisions from implementation details
+- Uses CONTEXT.md files at component roots
+
+**Tier 3: Feature (Frequently Changes)**
+- Implementation specifics, technical details, local patterns
+- Co-located with code for immediate updates
+- Minimizes documentation cascade when code changes
+- Uses CONTEXT.md files within feature directories
+
+## Benefits vs Traditional Systems
+
+### 1. Intelligent Context Loading
+
+**Traditional**: AI loads entire documentation corpus regardless of task
+**3-Tier**: Commands load only relevant tiers based on complexity
+
+Example:
+- Simple query → Tier 1 only (minimal tokens)
+- Component work → Tier 1 + relevant Tier 2
+- Deep implementation → All relevant tiers
+
+### 2. Maintenance Efficiency
+
+**Traditional**: Update multiple documents for each change
+**3-Tier**: Updates isolated to appropriate tier
+
+Example:
+- API endpoint change → Update only Tier 3 API documentation
+- New component → Add Tier 2 documentation, Tier 1 unchanged
+- Coding standard → Update only Tier 1, applies everywhere
+
+### 3. AI Performance Optimization
+
+**Traditional**: AI struggles to find relevant information
+**3-Tier**: Structured hierarchy guides AI to precise context
+
+The system provides:
+- Clear routing logic for agent navigation
+- Predictable documentation locations
+- Efficient token usage through targeted loading
+
+## Integration with Kit Components
+
+### Command Integration
+
+Commands leverage the 3-tier structure for intelligent operation:
+
+```
+Command Execution → Analyze Task Complexity → Load Appropriate Tiers
+                                            ↓
+                                   Simple: Tier 1 only
+                                   Component: Tiers 1-2
+                                   Complex: All relevant tiers
+```
+
+### MCP Server Integration
+
+External AI services receive proper context through the tier system:
+
+- **Gemini Consultations** - Auto-attach `project-structure.md` (Tier 1)
+- **Context7 Lookups** - Happen within established project context
+- **Recommendations** - Align with documented architecture
+
+### Multi-Agent Routing
+
+The documentation structure determines agent behavior:
+
+- Number of agents spawned based on tiers involved
+- Each agent receives targeted documentation subset
+- Parallel analysis without context overlap
+
+## Key Files and Their Roles
+
+### Foundation Files (ai-context/)
+
+**docs-overview.md**
+- Template for implementing 3-tier documentation
+- Maps documentation structure for AI navigation
+- [View Template](ai-context/docs-overview.md)
+
+**project-structure.md**
+- Complete technology stack and file organization
+- Required reading for all AI agents
+- Auto-attaches to Gemini consultations
+- [View Template](ai-context/project-structure.md)
+
+**system-integration.md**
+- Cross-component communication patterns
+- Integration architectures for multi-agent analysis
+- [View Template](ai-context/system-integration.md)
+
+**deployment-infrastructure.md**
+- Infrastructure patterns and constraints
+- Deployment context for AI recommendations
+- [View Template](ai-context/deployment-infrastructure.md)
+
+**handoff.md**
+- Session continuity between AI interactions
+- Task state preservation
+- [View Template](ai-context/handoff.md)
+
+### Context Templates
+
+**CLAUDE.md** (Tier 1)
+- Master AI context with coding standards
+- Project-wide instructions and patterns
+- [View Template](CLAUDE.md)
+
+**CONTEXT-tier2-component.md**
+- Component-level architectural context
+- [View Template](CONTEXT-tier2-component.md)
+
+**CONTEXT-tier3-feature.md**
+- Feature-specific implementation details
+- [View Template](CONTEXT-tier3-feature.md)
+
+## Implementation Strategy
+
+### 1. Start with Templates
+
+Use provided templates as foundation:
+- Copy and customize for your project
+- Maintain consistent structure
+- Focus on AI-consumable formatting
+
+### 2. Follow Natural Boundaries
+
+Let your architecture guide tier placement:
+- Stable decisions → Tier 1
+- Component design → Tier 2
+- Implementation details → Tier 3
+
+### 3. Co-locate Documentation
+
+Place CONTEXT.md files with related code:
+```
+backend/
+├── CONTEXT.md         # Backend architecture (Tier 2)
+└── src/
+    └── api/
+        └── CONTEXT.md # API implementation (Tier 3)
+```
+
+### 4. Maintain Hierarchy
+
+Ensure clear relationships:
+- Tier 3 references Tier 2 patterns
+- Tier 2 follows Tier 1 standards
+- No circular dependencies
+
+### 5. Use Documentation Commands
+
+The kit provides commands to manage documentation:
+- **`/create-docs`** - Generate initial documentation structure for projects without existing docs
+- **`/update-docs`** - Regenerate and update documentation after code changes to keep everything current
+
+## Measuring Success
+
+The 3-tier system succeeds when:
+
+1. **AI agents find context quickly** - No searching through irrelevant documentation
+2. **Updates stay localized** - Changes don't cascade unnecessarily
+3. **Documentation stays current** - Co-location ensures updates happen
+4. **Commands work efficiently** - Appropriate context loads automatically
+5. **MCP servers provide relevant advice** - External AI understands your project
+
+---
+
+*Part of the Claude Code Development Kit - see [main documentation](../README.md) for complete system overview.*

package/docs/ai-context/deployment-infrastructure.md

@@ -0,0 +1,21 @@
+# Deployment & Infrastructure Documentation
+
+This document contains deployment and infrastructure-related documentation for the project.
+
+## Purpose
+
+This template serves as a placeholder for documenting:
+- Deployment strategies and procedures
+- Infrastructure architecture and configuration
+- CI/CD pipelines and automation
+- Environment management
+- Monitoring and observability setup
+- Scaling strategies and considerations
+
+## Implementation Note
+
+Replace this template with your actual deployment and infrastructure documentation as your project develops. Focus on patterns and decisions that AI agents need to understand when working with infrastructure-related code or making architectural recommendations.
+
+---
+
+*Customize this template based on your specific deployment and infrastructure requirements.*

package/docs/ai-context/docs-overview.md

@@ -0,0 +1,89 @@
+# Documentation Architecture
+
+This project uses a **3-tier documentation system** that organizes knowledge by stability and scope, enabling efficient AI context loading and scalable development.
+
+## How the 3-Tier System Works
+
+**Tier 1 (Foundation)**: Stable, system-wide documentation that rarely changes - architectural principles, technology decisions, cross-component patterns, and core development protocols.
+
+**Tier 2 (Component)**: Architectural charters for major components - high-level design principles, integration patterns, and component-wide conventions without feature-specific details.
+
+**Tier 3 (Feature-Specific)**: Granular documentation co-located with code - specific implementation patterns, technical details, and local architectural decisions that evolve with features.
+
+This hierarchy allows AI agents to load targeted context efficiently while maintaining a stable foundation of core knowledge.
+
+## Documentation Principles
+- **Co-location**: Documentation lives near relevant code
+- **Smart Extension**: New documentation files created automatically when warranted
+- **AI-First**: Optimized for efficient AI context loading and machine-readable patterns
+
+## Tier 1: Foundational Documentation (System-Wide)
+
+- **[Master Context](/CLAUDE.md)** - *Essential for every session.* Coding standards, security requirements, MCP server integration patterns, and development protocols
+- **[Project Structure](/docs/ai-context/project-structure.md)** - *REQUIRED reading.* Complete technology stack, file tree, and system architecture. Must be attached to Gemini consultations
+- **[System Integration](/docs/ai-context/system-integration.md)** - *For cross-component work.* Communication patterns, data flow, testing strategies, and performance optimization
+- **[Deployment Infrastructure](/docs/ai-context/deployment-infrastructure.md)** - *Infrastructure patterns.* Containerization, monitoring, CI/CD workflows, and scaling strategies
+- **[Task Management](/docs/ai-context/handoff.md)** - *Session continuity.* Current tasks, documentation system progress, and next session goals
+
+## Tier 2: Component-Level Documentation
+
+### Backend Components
+- **[Backend Context](/backend/CONTEXT.md)** - *Server implementation.* API patterns, database integration, service architecture, and performance considerations
+- **[Worker Services](/workers/CONTEXT.md)** - *Background processing.* Job queue patterns, scheduling, and async task management
+- **[Shared Libraries](/shared/CONTEXT.md)** - *Reusable code.* Common utilities, shared types, and cross-component functionality
+
+### Frontend Components
+- **[Web Application](/frontend/CONTEXT.md)** - *Client implementation.* UI patterns, state management, routing, and user interaction patterns
+- **[Mobile Application](/mobile/CONTEXT.md)** - *Mobile implementation.* Platform-specific patterns, native integrations, and mobile optimizations
+- **[Admin Dashboard](/admin/CONTEXT.md)** - *Administrative interface.* Permission patterns, admin workflows, and management tools
+
+### Infrastructure Components
+- **[Infrastructure Code](/infrastructure/CONTEXT.md)** - *IaC patterns.* Terraform/CloudFormation templates, resource definitions, and deployment automation
+- **[Monitoring Setup](/monitoring/CONTEXT.md)** - *Observability patterns.* Metrics collection, alerting rules, and dashboard configurations
+
+## Tier 3: Feature-Specific Documentation
+
+Granular CONTEXT.md files co-located with code for minimal cascade effects:
+
+### Backend Feature Documentation
+- **[Core Services](/backend/src/core/services/CONTEXT.md)** - *Business logic patterns.* Service architecture, data processing, integration patterns, and error handling
+- **[API Layer](/backend/src/api/CONTEXT.md)** - *API patterns.* Endpoint design, validation, middleware, and request/response handling
+- **[Data Layer](/backend/src/data/CONTEXT.md)** - *Data patterns.* Database models, queries, migrations, and data access patterns
+- **[Authentication](/backend/src/auth/CONTEXT.md)** - *Auth patterns.* Authentication flows, authorization rules, session management, and security
+- **[Integrations](/backend/src/integrations/CONTEXT.md)** - *External services.* Third-party API clients, webhook handlers, and service adapters
+
+### Frontend Feature Documentation
+- **[UI Components](/frontend/src/components/CONTEXT.md)** - *Component patterns.* Reusable components, styling patterns, accessibility, and composition strategies
+- **[State Management](/frontend/src/store/CONTEXT.md)** - *State patterns.* Global state, local state, data flow, and persistence strategies
+- **[API Client](/frontend/src/api/CONTEXT.md)** - *Client patterns.* HTTP clients, error handling, caching, and data synchronization
+- **[Routing](/frontend/src/routes/CONTEXT.md)** - *Navigation patterns.* Route definitions, guards, lazy loading, and deep linking
+- **[Utilities](/frontend/src/utils/CONTEXT.md)** - *Helper functions.* Formatters, validators, transformers, and common utilities
+
+### Shared Feature Documentation
+- **[Common Types](/shared/src/types/CONTEXT.md)** - *Type definitions.* Shared interfaces, enums, and type utilities
+- **[Validation Rules](/shared/src/validation/CONTEXT.md)** - *Validation patterns.* Schema definitions, custom validators, and error messages
+- **[Constants](/shared/src/constants/CONTEXT.md)** - *Shared constants.* Configuration values, enums, and magic numbers
+- **[Utilities](/shared/src/utils/CONTEXT.md)** - *Shared utilities.* Cross-platform helpers, formatters, and common functions
+
+
+
+## Adding New Documentation
+
+### New Component
+1. Create `/new-component/CONTEXT.md` (Tier 2)
+2. Add entry to this file under appropriate section
+3. Create feature-specific Tier 3 docs as features develop
+
+### New Feature
+1. Create `/component/src/feature/CONTEXT.md` (Tier 3)
+2. Reference parent component patterns
+3. Add entry to this file under component's features
+
+### Deprecating Documentation
+1. Remove obsolete CONTEXT.md files
+2. Update this mapping document
+3. Check for broken references in other docs
+
+---
+
+*This documentation architecture template should be customized to match your project's actual structure and components. Add or remove sections based on your architecture.*