codebase-explorer
// 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.
$ git log --oneline --stat
stars:194
forks:37
updated:March 4, 2026
SKILL.mdreadonly
SKILL.md Frontmatter
namecodebase-explorer
descriptionExplore 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:
- 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"