Code Explanation

Understand code through everyday analogies, ASCII art diagrams, and step-by-step walkthroughs.

Explanation Framework

When explaining code, always include:

•Start with an analogy - Compare to something from everyday life
•Draw a diagram - Use ASCII art for flow/structure/relationships
•Walk through the code - Step-by-step explanation
•Highlight a gotcha - Common mistakes or misconceptions

Keep explanations conversational. For complex concepts, use multiple analogies.

Example: Simple Function

Function: Calculate transaction similarity

Analogy: Like comparing twins - measuring how alike two descriptions are.

Diagram:

code

Transaction A: "STARBUCKS #123"
Transaction B: "STARBUCKS #456"
               │
               ▼
         ┌─────────────┐
         │  Compare    │
         │  Character  │
         │  by Character│
         └──────┬──────┘
                │
                ▼
         ┌─────────────┐
         │ Similarity: │
         │    0.92     │
         │   (92%)     │
         └─────────────┘

Walk through:

python

from difflib import SequenceMatcher

def calculate_similarity(desc1, desc2):
    # Compare strings character by character
    matcher = SequenceMatcher(None, desc1.lower(), desc2.lower())

    # Get ratio (0.0 to 1.0)
    return matcher.ratio()

# Example
similarity = calculate_similarity(
    "STARBUCKS #123",
    "STARBUCKS #456"
)
# Returns: 0.92 (92% similar)

Gotcha: Case matters! Always .lower() both strings first.

Quick Explanations

Data Flow

code

User Input → Validation → Database → Processing → Response
    │            │           │           │           │
    └──────── Error Handling Throughout ────────────┘

API Request Flow

code

Frontend (React)
    │
    ▼ fetch()
Backend (FastAPI)
    │
    ▼ query()
Database (SQLite)
    │
    ▼ results
Backend
    │
    ▼ JSON response
Frontend (updates UI)

Classification Logic

code

Transaction arrives
    │
    ▼
Check history
    │
    ├─ Found? → Reuse category
    │
    └─ Not found? → ML predict
              │
              ▼
         Assign category

Domain Concepts

Complete Budget Buddy examples with detailed diagrams: See DOMAIN_EXAMPLES.md

Includes:

•Transaction Classification Pipeline - How transactions get categorized
•Fuzzy Matching (0.85 threshold) - Finding similar transactions
•Budget Allocation Flow - How monthly budgets work
•Sinking Funds Mechanics - Goal-based saving system
•Buddy AI Insight Generation - Automated AI analysis workflow

Each example includes:

•Real-world analogy
•ASCII diagram
•Step-by-step code walkthrough
•Common gotchas

Explaining Process

Step 1: Start with Analogy

Bad: "This function uses SequenceMatcher from difflib..."

Good: "Think of this like finding twins in a crowd. We're looking for fraternal twins (similar but not identical) by checking how much they look alike."

Step 2: Draw the Flow

Use ASCII art to show:

•Data flow (→, ↓, ▼)
•Decision points (├, └)
•Processes (boxes)
•Results (final state)

Step 3: Code Walkthrough

Show actual code with comments explaining each part:

python

# Step 1: Get reference transaction
ref_tx = get_transaction(123)

# Step 2: Find candidates
candidates = db.query(Transaction).filter(
    Transaction.bb_category_manual == False  # Only unclassified
).all()

# Step 3: Calculate similarity
for candidate in candidates:
    similarity = calculate_similarity(ref_tx.description, candidate.description)
    if similarity >= 0.85:  # Our threshold
        matches.append(candidate)

Step 4: Point Out Gotchas

"Gotcha: The threshold is 0.85 (85%). Lower = more matches but more false positives. Higher = fewer matches but more accurate."

Common Patterns in Budget Buddy

Pattern: Transaction Flow

code

Plaid API → Import → Classify → Store → Display
                        │
                        └─→ ML Model (if new merchant)

Pattern: User Action Flow

code

User clicks → React event → API call → Backend processing → Database update → API response → UI update

Pattern: Weekly Cron

code

Cron triggers → Gather data → Call Claude API → Parse response → Save to DB → Display in UI

Tips for Good Explanations

•Assume Claude knows basics - Don't explain what a database is
•Focus on "why" - Why 0.85 threshold? Why this pattern?
•Show data transformations - Input → Processing → Output
•Use real examples - Actual transaction descriptions, real amounts
•Mention edge cases - What if no transactions? What if API fails?

Integration with Other Skills

•Transaction Classification Debugger - Explains fuzzy matching in depth
•Frontend UI/UX Design - Explains component structure
•Buddy AI Setup - Explains cron and insight generation

References

•DOMAIN_EXAMPLES.md - Complete Budget Buddy concept explanations
•/backend/services/ - Core business logic to explain
•/frontend/src/components/ - UI components to explain

Last Updated

January 1, 2026