codebase-explorer

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

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"