# Context Map: Knowledge Architecture Guide

## Overview

This document serves as your navigation guide to the comprehensive knowledge architecture built for the mixpanel-react-native codebase. Each resource is designed for specific use cases and depths of understanding.

## 🎯 Quick Decision Tree

**I need to...**

- **🚀 Start immediately** → Read `CLAUDE.md` Quick Reference section
- **🔍 Find a specific file** → Use `codebase-map.md` 
- **🐛 Debug an issue** → Go to `workflows/03-debugging-issues.md`
- **⚙️ Add a new feature** → Follow `workflows/01-adding-new-features.md`
- **🧪 Write tests** → Use `workflows/02-testing-changes.md`
- **🏗️ Understand architecture** → Read `architecture/system-design.md`
- **📝 Learn coding patterns** → Study `discovered-patterns.md`
- **🔧 Configure technologies** → Check `technologies/` directory

## 📚 Knowledge Resources

### 🎯 CLAUDE.md (Enhanced)
**Purpose**: Your daily driver - immediate reference with discovered insights
**When to use**: 
- Starting any task
- Quick commands and patterns
- Implementation mode debugging
- File location lookup

**Key sections**:
- Discovered Conventions (most important patterns)
- Critical Workflows (3 most common tasks)
- Quick Reference (commands, file locations, constants)

### 🗺️ codebase-map.md
**Purpose**: High-level structural understanding and file organization
**When to use**:
- New to the codebase
- Looking for specific functionality
- Understanding overall architecture
- Planning changes across modules

**Key insights**:
- Executive summary of architectural strategy
- File organization by purpose
- Entry points and configuration
- Sample application structure

### 🧬 discovered-patterns.md  
**Purpose**: Deep dive into coding conventions and design philosophies
**When to use**:
- Writing new code
- Refactoring existing code
- Understanding team conventions
- Code review preparation

**Key patterns**:
- Naming conventions across all types
- Error handling philosophy
- Async patterns and performance optimization
- Testing strategies

## 🏗️ Architecture Resources

### 📐 architecture/system-design.md
**Purpose**: Complete system architecture with data flows and design decisions
**When to use**:
- Planning major changes
- Understanding data flow
- Performance optimization
- Architectural decisions

**Contains**:
- High-level architecture diagrams (ASCII)
- Detailed data flow documentation
- Layer-by-layer system breakdown
- Design trade-offs and reasoning

## 🔧 Technology Resources

### ⚛️ technologies/react-native.md
**Purpose**: React Native integration patterns and native module bridging
**When to use**:
- Native module development
- Bridge debugging
- Platform-specific issues
- Autolinking problems

### 🧪 technologies/jest.md
**Purpose**: Testing patterns and mocking strategies
**When to use**:
- Writing comprehensive tests
- Setting up new test scenarios
- Debugging test failures
- Understanding mocking patterns

### 💾 technologies/async-storage.md
**Purpose**: Storage abstraction and persistence patterns
**When to use**:
- Storage-related issues
- Performance optimization
- Data migration scenarios
- Cross-platform storage concerns

## 🔄 Workflow Resources

### 1️⃣ workflows/01-adding-new-features.md
**Purpose**: Step-by-step guide for feature development
**When to use**:
- Adding any new functionality
- Following dual-implementation pattern
- Ensuring comprehensive testing
- Maintaining compatibility

**Covers**: API design → Native implementation → JS fallback → Testing → Documentation

### 2️⃣ workflows/02-testing-changes.md
**Purpose**: Complete testing methodology and patterns
**When to use**:
- Testing new features
- Regression testing
- CI/CD setup
- Debugging test failures

**Covers**: Unit tests → Integration tests → Manual testing → Performance testing

### 3️⃣ workflows/03-debugging-issues.md
**Purpose**: Systematic debugging approach for common problems
**When to use**:
- Any issue investigation
- Silent failures
- Performance problems
- Platform-specific bugs

**Covers**: Diagnostics → Native debugging → JS debugging → Network issues → Common scenarios

## 🎨 Usage Patterns by Role

### New Team Member
1. Start with `codebase-map.md` for overview
2. Read `discovered-patterns.md` to understand conventions  
3. Use `CLAUDE.md` for daily reference
4. Practice with `workflows/01-adding-new-features.md`

### Debugging Developer
1. Check `CLAUDE.md` Quick Reference first
2. Use `workflows/03-debugging-issues.md` systematically
3. Consult relevant `technologies/` docs for specific issues
4. Reference `architecture/system-design.md` for complex problems

### Feature Developer
1. Plan with `workflows/01-adding-new-features.md`
2. Reference `discovered-patterns.md` for coding style
3. Test with `workflows/02-testing-changes.md`
4. Use technology-specific docs as needed

### Architecture Reviewer
1. Review `architecture/system-design.md` for current state
2. Check `discovered-patterns.md` for established conventions
3. Use `codebase-map.md` to understand impact scope

## 🔍 Depth Levels

### Surface Level (5 minutes)
- `CLAUDE.md` Quick Reference section
- File location lookups
- Common commands

### Working Level (30 minutes)  
- Complete `CLAUDE.md` read
- Relevant workflow document
- Technology-specific patterns

### Deep Level (2 hours)
- `architecture/system-design.md` complete study
- `discovered-patterns.md` full analysis
- Multiple workflow documents

### Mastery Level (Full day)
- All documents studied
- Workflows practiced
- Technology docs internalized

## 📈 Knowledge Maintenance

### When to Update

**After major changes**:
- New architectural patterns discovered
- Technology integrations changed
- Testing strategies evolved
- Common workflows identified

### What to Watch For

**Pattern Evolution**:
- New error handling approaches
- Performance optimization techniques
- Testing methodology improvements
- Technology upgrade impacts

**Workflow Changes**:
- New development practices
- Build process modifications
- Debugging technique improvements

### Update Process

1. **Identify changed patterns** in code review
2. **Update relevant documents** with new discoveries
3. **Revise CLAUDE.md** if critical workflows change
4. **Test workflow accuracy** with sample implementations

## 🎯 Success Metrics

### Effective Usage Indicators
- **Reduced onboarding time** for new team members
- **Consistent code patterns** across contributions
- **Faster debugging** with systematic approaches
- **Fewer architectural questions** during development

### Knowledge Architecture Health
- **Documents stay current** with codebase evolution
- **Workflows remain accurate** for actual development
- **Examples still work** with current codebase state
- **Patterns reflect reality** of current development practices

## 🚀 Getting Started Recommendations

### First-Time Users
1. Skim `CLAUDE.md` for immediate context (5 min)
2. Read `codebase-map.md` for structural understanding (15 min)
3. Try a workflow document for hands-on learning (30 min)

### Returning Users  
1. Check `CLAUDE.md` Quick Reference for immediate needs
2. Jump directly to relevant workflow or technology document
3. Use architecture docs for complex decisions

### Emergency Debugging
1. `CLAUDE.md` debugging section for quick diagnostics
2. `workflows/03-debugging-issues.md` for systematic approach
3. Technology-specific docs for deep issues

This knowledge architecture is designed to grow with the codebase and provide value at every level of engagement, from quick references to deep architectural understanding.