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

src/types/database/user-profile.ts

src/types/database/organization-tenant.ts

src/types/database/project-management.ts

src/types/database/content-media.ts

src/types/database/story-ownership.ts

src/types/database/cultural-sensitivity.ts

src/types/database/location-events.ts

src/types/database/analysis-support.ts

Supabase Clients

src/lib/supabase/client.ts

src/lib/supabase/client-ssr.ts

src/lib/supabase/service-role-client.ts

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"