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:
- Database Schema - Tables, relationships, migrations
- Data Flow - Supabase → Services → API Routes → Components
- Service Layer - Business logic patterns
- API Routes - Endpoints and their purposes
- Type Definitions - Where to find types for each domain
- 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)
- elder (100) - Cultural authority
- cultural_keeper (90) - Knowledge preservation
- admin (70) - System management
- project_leader (60) - Project management
- storyteller (50) - Content creation
- community_member (40) - Participant
- 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:
- File locations with clickable links
- Key relationships between tables/services
- Code snippets showing patterns
- 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"