# 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