Agent-Skills.md

Agent Skills: Codebase Explorer Skill

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.

UncategorizedID: aiskillstore/marketplace/codebase-explorer

Repository

aiskillstore/marketplace
aiskillstore
23014

Install this agent skill to your local

pnpm dlx add-skill https://github.com/aiskillstore/marketplace/tree/HEAD/skills/acurioustractor/codebase-explorer

Skill Files

Browse the full folder contents for codebase-explorer.

Download Skill

Loading file tree…

skills/acurioustractor/codebase-explorer/SKILL.md

Skill Metadata

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:

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