@meldscience/meld

# Project Documentation Strategy CLAUDE: DO NOT EDIT THIS FILE WITHOUT A CONVERSATION ABOUT CHANGES FIRST. This document explains how we organize and maintain project documentation. Our approach separates concerns into distinct documents while ensuring they work together to provide a complete picture of the system. ## Documentation Structure ### README.md - User Experience - **Purpose**: Describes how users interact with the system - **Answers**: "What does it do?" and "Why does it work this way?" - **Focus**: Behavior, interactions, and user-facing features - **Example**: "Users can see their context window usage as a percentage" ### PLAN.md - Implementation Strategy - **Purpose**: Outlines how we build the system - **Answers**: "How do we build it?" and "When do we add features?" - **Focus**: Technical decisions, implementation stages, and architecture - **Example**: "Implement context tracking in phase 2 using Prisma for storage" ### TREE.md - Code Organization - **Purpose**: Maps the codebase structure and relationships - **Answers**: "Where is the code?" and "How does it fit together?" - **Focus**: File structure, component relationships, and data flows - **Example**: ``` src/ ├── core/ │ └── context/ │ ├── tracker.ts │ │ # Context Window Management │ │ └── class ContextWindowTracker │ │ # Tracks and manages context window usage │ │ # Maintains 80% safety margin of Claude's max window │ │ │ │ │ # Data Flow: │ │ # 1. Incoming messages → calculate token usage │ │ # 2. Context chain → accumulate total usage │ │ # 3. Emits events at usage thresholds │ │ │ │ │ ├── calculateUsage(message: string): number │ │ │ # Estimates token usage for new content │ │ │ │ │ ├── getChainUsage(messageId: string): Promise<number> │ │ │ # Calculates full conversation chain usage │ │ │ # Pulls messages from ConversationModel │ │ │ # Returns percentage of safe window size │ │ │ │ │ └── shouldPruneContext(): boolean │ │ # Determines if context needs pruning │ │ # Triggers at configurable thresholds │ ├── db/ │ └── models/ │ └── conversations.ts │ # Conversation Storage and Retrieval │ └── class ConversationModel │ # Manages conversation persistence │ │ │ # Data Flow: │ # 1. New messages → append to chain │ # 2. Chain retrieval → ordered by timestamp │ # 3. Context pruning → mark messages as archived │ │ │ ├── async getConversationChain() │ │ # Retrieves full message chain │ │ # Includes metadata for context tracking │ │ # Returns: messages[], totalTokens, isAtLimit │ │ │ └── async pruneContext() │ # Archives older messages when near limit │ # Maintains conversation coherence │ # Updates context window tracking │ ├── discord/ │ └── client.ts │ └── class DiscordClient │ # Discord Interface │ │ │ # Data Flow: │ # 1. User message → new conversation entry │ # 2. Context check → before processing │ # 3. Usage warning → notify user if near limit │ │ │ ├── handleMessage() │ │ # Checks context window before processing │ │ # Notifies user of usage/pruning │ │ │ └── sendContextWarning() │ # Formats and sends usage warnings │ # Explains pruning if activated ``` ## Documentation Principles ### 1. Development Pattern We follow a specific pattern when developing features: 1. **Define the Experience** (UX.md) - Determine exactly how it should work for users - Document user interactions and expectations - Define success criteria from user perspective 2. **Plan the Implementation** (PLAN.md) - Create strategy to deliver the experience - Make key architectural decisions - Define implementation stages 3. **Structure the Code** (TREE.md) - Design precise code organization - Document component relationships - Map data flows through the system This pattern ensures we: - Start with user needs - Build with clear purpose - Maintain clean architecture ### 2. Separation of Concerns Each document has a specific focus: - UX.md → User perspective - PLAN.md → Builder perspective - TREE.md → Code perspective ### 3. Data Flow Documentation Rather than creating a separate DATA.md, we document data flows directly in TREE.md: - Show data transformations at their points of occurrence - Document flow direction with arrows (→) - Include decision points and state changes - Keep implementation details with their context Example: ``` # Data Flow: # 1. User message → new conversation entry # 2. Context check → before processing # 3. Usage warning → notify user if near limit ``` ### 4. TREE.md Evolution TREE.md serves different purposes during different phases of development: 1. Planning Phase - Acts as detailed pseudo-code - Contains implementation specifics - Describes data structures and relationships - Serves as a blueprint for development 2. Implementation Phase - Gradually removes implementation details as they move into actual code - Shifts focus to navigation and relationships between components - Points to actual code for specifics - Maintains data flow documentation 3. Maintenance Phase - Serves as a high-level map of the codebase - Focuses on component relationships and data flows - Trusts actual code (types, models, schemas) to provide implementation details - Avoids duplicating information that exists in code Remember: TREE.md should complement, not compete with, the actual implementation. ### 5. Cross-Document References Features often span multiple documents: - UX.md: How users experience the feature - PLAN.md: How/when we implement it - TREE.md: Where the code lives Example: Context Window Tracking - UX.md: Describes the 80% warning experience - PLAN.md: Details the implementation strategy - TREE.md: Shows the component relationships ### 6. Configuration Configuration lives in a dedicated `config/` directory: - YAML files for runtime configuration - Schema definitions - Documentation of config→code mapping ## Maintenance Guidelines ### When to Update Each Document - **UX.md**: When user-facing behavior changes - **PLAN.md**: When implementation strategy shifts - **TREE.md**: When code structure changes ### Document Relationships ``` UX.md ↓ PLAN.md → Describes how to build the UX ↓ TREE.md → Shows where the code lives ``` ### Adding New Features 1. Start with UX.md - define the user experience 2. Update PLAN.md - decide implementation strategy 3. Modify TREE.md - document code organization ## Working with These Docs ### For Contributors - Read UX.md first to understand goals - Check PLAN.md for implementation context - Use TREE.md for navigation ### For Maintainers - Keep docs in sync when making changes - Update data flows when modifying components - Ensure cross-document consistency ### For AI Assistants - Use these docs to understand context - Reference specific sections when discussing changes - Maintain documentation style and structure