cim_summary/CODE_SUMMARY_TEMPLATE.md

# Code Summary Template
## Standardized Documentation Format for LLM Agent Understanding

### 📋 Template Usage
Use this template to document individual files, services, or components. This format is optimized for LLM coding agents to quickly understand code structure, purpose, and implementation details.

---

## 📄 File Information

**File Path**: `[relative/path/to/file]`  
**File Type**: `[TypeScript/JavaScript/JSON/etc.]`  
**Last Updated**: `[YYYY-MM-DD]`  
**Version**: `[semantic version]`  
**Status**: `[Active/Deprecated/In Development]`

---

## 🎯 Purpose & Overview

**Primary Purpose**: `[What this file/service does in one sentence]`

**Business Context**: `[Why this exists, what problem it solves]`

**Key Responsibilities**:
- `[Responsibility 1]`
- `[Responsibility 2]`
- `[Responsibility 3]`

---

## 🏗️ Architecture & Dependencies

### Dependencies
**Internal Dependencies**:
- `[service1.ts]` - `[purpose of dependency]`
- `[service2.ts]` - `[purpose of dependency]`

**External Dependencies**:
- `[package-name]` - `[version]` - `[purpose]`
- `[API service]` - `[purpose]`

### Integration Points
- **Input Sources**: `[Where data comes from]`
- **Output Destinations**: `[Where data goes]`
- **Event Triggers**: `[What triggers this service]`
- **Event Listeners**: `[What this service triggers]`

---

## 🔧 Implementation Details

### Core Functions/Methods

#### `[functionName]`
```typescript
/**
 * @purpose [What this function does]
 * @context [When/why it's called]
 * @inputs [Parameter types and descriptions]
 * @outputs [Return type and format]
 * @dependencies [What it depends on]
 * @errors [Possible errors and conditions]
 * @complexity [Time/space complexity if relevant]
 */
```

**Example Usage**:
```typescript
// Example of how to use this function
const result = await functionName(input);
```

### Data Structures

#### `[TypeName]`
```typescript
interface TypeName {
  property1: string;    // Description of property1
  property2: number;    // Description of property2
  property3?: boolean;  // Optional description of property3
}
```

### Configuration
```typescript
// Key configuration options
const CONFIG = {
  timeout: 30000,        // Request timeout in ms
  retryAttempts: 3,      // Number of retry attempts
  batchSize: 10,         // Batch processing size
};
```

---

## 📊 Data Flow

### Input Processing
1. `[Step 1 description]`
2. `[Step 2 description]`
3. `[Step 3 description]`

### Output Generation
1. `[Step 1 description]`
2. `[Step 2 description]`
3. `[Step 3 description]`

### Data Transformations
- `[Input Type]` → `[Transformation]` → `[Output Type]`
- `[Input Type]` → `[Transformation]` → `[Output Type]`

---

## 🚨 Error Handling

### Error Types
```typescript
/**
 * @errorType VALIDATION_ERROR
 * @description [What causes this error]
 * @recoverable [true/false]
 * @retryStrategy [retry approach]
 * @userMessage [Message shown to user]
 */

/**
 * @errorType PROCESSING_ERROR
 * @description [What causes this error]
 * @recoverable [true/false]
 * @retryStrategy [retry approach]
 * @userMessage [Message shown to user]
 */
```

### Error Recovery
- **Validation Errors**: `[How validation errors are handled]`
- **Processing Errors**: `[How processing errors are handled]`
- **System Errors**: `[How system errors are handled]`

### Fallback Strategies
- **Primary Strategy**: `[Main approach]`
- **Fallback Strategy**: `[Backup approach]`
- **Degradation Strategy**: `[Graceful degradation]`

---

## 🧪 Testing

### Test Coverage
- **Unit Tests**: `[Coverage percentage]` - `[What's tested]`
- **Integration Tests**: `[Coverage percentage]` - `[What's tested]`
- **Performance Tests**: `[What performance aspects are tested]`

### Test Data
```typescript
/**
 * @testData [test data name]
 * @description [Description of test data]
 * @size [Size if relevant]
 * @expectedOutput [What should be produced]
 */
```

### Mock Strategy
- **External APIs**: `[How external APIs are mocked]`
- **Database**: `[How database is mocked]`
- **File System**: `[How file system is mocked]`

---

## 📈 Performance Characteristics

### Performance Metrics
- **Average Response Time**: `[time]`
- **Memory Usage**: `[memory]`
- **CPU Usage**: `[CPU]`
- **Throughput**: `[requests per second]`

### Optimization Strategies
- **Caching**: `[Caching approach]`
- **Batching**: `[Batching strategy]`
- **Parallelization**: `[Parallel processing]`
- **Resource Management**: `[Resource optimization]`

### Scalability Limits
- **Concurrent Requests**: `[limit]`
- **Data Size**: `[limit]`
- **Rate Limits**: `[limits]`

---

## 🔍 Debugging & Monitoring

### Logging
```typescript
/**
 * @logging [Logging configuration]
 * @levels [Log levels used]
 * @correlation [Correlation ID strategy]
 * @context [Context information logged]
 */
```

### Debug Tools
- **Health Checks**: `[Health check endpoints]`
- **Metrics**: `[Performance metrics]`
- **Tracing**: `[Request tracing]`

### Common Issues
1. **Issue 1**: `[Description]` - `[Solution]`
2. **Issue 2**: `[Description]` - `[Solution]`
3. **Issue 3**: `[Description]` - `[Solution]`

---

## 🔐 Security Considerations

### Input Validation
- **File Types**: `[Allowed file types]`
- **File Size**: `[Size limits]`
- **Content Validation**: `[Content checks]`

### Authentication & Authorization
- **Authentication**: `[How authentication is handled]`
- **Authorization**: `[How authorization is handled]`
- **Data Isolation**: `[How data is isolated]`

### Data Protection
- **Encryption**: `[Encryption approach]`
- **Sanitization**: `[Data sanitization]`
- **Audit Logging**: `[Audit trail]`

---

## 📚 Related Documentation

### Internal References
- `[related-file1.ts]` - `[relationship]`
- `[related-file2.ts]` - `[relationship]`
- `[related-file3.ts]` - `[relationship]`

### External References
- `[API Documentation]` - `[URL]`
- `[Library Documentation]` - `[URL]`
- `[Architecture Documentation]` - `[URL]`

---

## 🔄 Change History

### Recent Changes
- `[YYYY-MM-DD]` - `[Change description]` - `[Author]`
- `[YYYY-MM-DD]` - `[Change description]` - `[Author]`
- `[YYYY-MM-DD]` - `[Change description]` - `[Author]`

### Planned Changes
- `[Future change 1]` - `[Target date]`
- `[Future change 2]` - `[Target date]`

---

## 📋 Usage Examples

### Basic Usage
```typescript
// Basic example of how to use this service
import { ServiceName } from './serviceName';

const service = new ServiceName();
const result = await service.processData(input);
```

### Advanced Usage
```typescript
// Advanced example with configuration
import { ServiceName } from './serviceName';

const service = new ServiceName({
  timeout: 60000,
  retryAttempts: 5,
  batchSize: 20
});

const results = await service.processBatch(dataArray);
```

### Error Handling
```typescript
// Example of error handling
try {
  const result = await service.processData(input);
} catch (error) {
  if (error.type === 'VALIDATION_ERROR') {
    // Handle validation error
  } else if (error.type === 'PROCESSING_ERROR') {
    // Handle processing error
  }
}
```

---

## 🎯 LLM Agent Notes

### Key Understanding Points
- `[Important concept 1]`
- `[Important concept 2]`
- `[Important concept 3]`

### Common Modifications
- `[Common change 1]` - `[How to implement]`
- `[Common change 2]` - `[How to implement]`

### Integration Patterns
- `[Integration pattern 1]` - `[When to use]`
- `[Integration pattern 2]` - `[When to use]`

---

## 📝 Template Usage Instructions

### For New Files
1. Copy this template
2. Fill in all sections with relevant information
3. Remove sections that don't apply
4. Add sections specific to your file type
5. Update the file information header

### For Existing Files
1. Use this template to document existing code
2. Focus on the most important sections first
3. Add examples and usage patterns
4. Include error scenarios and solutions
5. Document performance characteristics

### Maintenance
- Update this documentation when code changes
- Keep examples current and working
- Review and update performance metrics regularly
- Maintain change history for significant updates

---

This template ensures consistent, comprehensive documentation that LLM agents can quickly parse and understand, leading to more accurate code evaluation and modification suggestions.