codebase-explorer

# 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:
```typescript
// 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

```bash
# 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](../../../docs/ARCHITECTURE_REFERENCE.md) - Complete system documentation

---

**Trigger:** User asks about codebase structure, data flow, or "how does X connect to Y"