---

name: codebase-explorer description: Explore and understand the Empathy Ledger codebase architecture, data flows, database schema, services, and how components connect. Use when you need to understand where things are, how data flows, or how different parts of the system relate to each other.

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

CopyUser 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:

Copy// 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

Copy# 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"