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

| Domain | Types File | Key Tables | |--------|-----------|-----------| | Users/Profiles | src/types/database/user-profile.ts | profiles, profile_settings | | Organizations | src/types/database/organization-tenant.ts | organisations, organization_members, tenants | | Projects | src/types/database/project-management.ts | projects, project_participants | | Stories/Content | src/types/database/content-media.ts | stories, transcripts, media_assets | | Distribution | src/types/database/story-ownership.ts | story_distributions, consent_proofs | | Cultural Safety | src/types/database/cultural-sensitivity.ts | cultural_safety_moderation | | Locations | src/types/database/location-events.ts | locations, events | | Analysis | src/types/database/analysis-support.ts | transcript_analysis, themes, quotes |

Supabase Clients

| Client | File | Usage | |--------|------|-------| | Browser | src/lib/supabase/client.ts | React components | | Server SSR | src/lib/supabase/client-ssr.ts | API routes, server components | | Service Role | src/lib/supabase/service-role-client.ts | Admin operations (bypasses RLS) |

Core Services (src/lib/services/)

| Service | Purpose | |---------|---------| | consent.service.ts | GDPR consent proof system | | distribution.service.ts | Story distribution with policy enforcement | | revocation.service.ts | Revoke distributed content | | embed.service.ts | Embedded story tokens | | organization.service.ts | Org management and metrics | | audit.service.ts | Compliance logging | | gdpr.service.ts | Data privacy operations | | webhook.service.ts | Event distribution to partners |

API Routes (src/app/api/)

| Route | Purpose | |-------|---------| | /api/stories | Story CRUD | | /api/stories/[id]/consent | Consent management | | /api/stories/[id]/distributions | Distribution tracking | | /api/stories/[id]/revoke | Revocation | | /api/storytellers | Storyteller profiles | | /api/projects | Project management | | /api/projects/[id]/transcripts | Transcript access | | /api/embed/stories/[id] | Embedded content | | /api/admin/* | Admin operations |

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"