Codebase Explorer Skill

Explore and document the Empathy Ledger codebase architecture, data flows, and system relationships.

Instructions

When this skill is invoked, help the user understand:

1. Database Schema – Tables, relationships, migrations
2. Data Flow – Supabase → Services → API Routes → Components
3. Service Layer – Business logic patterns
4. API Routes – Endpoints and their purposes
5. Type Definitions – Where to find types for each domain
6. Multi-Tenant Architecture – How tenant isolation works

Quick Reference Files

Database & Types

Supabase Clients

Core Services (src/lib/services/)

API Routes (src/app/api/)

Data Flow Pattern

User Action (React Component)
    ↓
fetch('/api/endpoint')
    ↓
API Route (src/app/api/*)
    ↓
Service Layer (src/lib/services/*)
    ↓
Supabase Client (RLS enforced)
    ↓
PostgreSQL (supabase/migrations/*)

Multi-Tenant Isolation

Every query filters by tenant:

// In API route
const profile = await supabase.from('profiles').select('tenant_id').eq('id', user.id).single()
query = query.eq('tenant_id', profile.tenant_id)

Role Hierarchy (highest → lowest)

1. elder (100) – Cultural authority
2. cultural_keeper (90) – Knowledge preservation
3. admin (70) – System management
4. project_leader (60) – Project management
5. storyteller (50) – Content creation
6. community_member (40) – Participant
7. guest (10) – Read-only

Common Exploration Commands

# Find all services
ls src/lib/services/

# Find API routes for a feature
ls src/app/api/stories/

# Check database types
cat src/types/database/index.ts

# View latest migration
ls -la supabase/migrations/ | tail -5

# Find where a table is used
grep -r "from('stories')" src/

# Find component for a feature
ls src/components/stories/

Output Format

When exploring, provide:

1. File locations with clickable links
2. Key relationships between tables/services
3. Code snippets showing patterns
4. Diagrams using ASCII or markdown tables

When to Use This Skill

Invoke when:

• Asking “where is X located?”
• Asking “how does X connect to Y?”
• Needing to understand data relationships
• Looking for the right service or API route
• Understanding the database schema
• Finding component or type definitions

Reference Documentation

For comprehensive documentation with full code examples, see:

• ARCHITECTURE_REFERENCE.md – Complete system documentation

Trigger: User asks about codebase structure, data flow, or “how does X connect to Y”