codebase-navigator

name	codebase-navigator
description	Navigate, search, and understand the Resume Matcher codebase using ripgrep, ack, or grep. Find functions, classes, components, API endpoints, trace data flows, and understand architecture. Use FIRST when exploring code, finding files, or understanding project structure.

Codebase Navigator

Use this skill FIRST when exploring code, finding files, or understanding project structure.

Search Scripts

Run from the repo root:

# Find functions/methods
.github/skills/codebase-navigator/scripts/search.sh functions <pattern>

# Find React components
.github/skills/codebase-navigator/scripts/search.sh components <pattern>

# Find API endpoints
.github/skills/codebase-navigator/scripts/search.sh endpoints

# Find classes, types, schemas
.github/skills/codebase-navigator/scripts/search.sh classes <pattern>
.github/skills/codebase-navigator/scripts/search.sh types <pattern>
.github/skills/codebase-navigator/scripts/search.sh schema <pattern>

# Find imports, exports, hooks, config
.github/skills/codebase-navigator/scripts/search.sh imports <module>
.github/skills/codebase-navigator/scripts/search.sh exports <pattern>
.github/skills/codebase-navigator/scripts/search.sh hooks <pattern>
.github/skills/codebase-navigator/scripts/search.sh config

# Find usages and dependents
.github/skills/codebase-navigator/scripts/search.sh usage <symbol>
.github/skills/codebase-navigator/scripts/search.sh deps <file>

# List API routes, TODOs, files, project tree
.github/skills/codebase-navigator/scripts/search.sh api-routes
.github/skills/codebase-navigator/scripts/search.sh todos
.github/skills/codebase-navigator/scripts/search.sh files <pattern>
.github/skills/codebase-navigator/scripts/search.sh tree [dir]

Trace Scripts

# Trace an API endpoint from route -> service -> schema -> frontend
.github/skills/codebase-navigator/scripts/trace.sh api-flow <endpoint>

# Find component hierarchy (parents and children)
.github/skills/codebase-navigator/scripts/trace.sh component-tree <ComponentName>

# Trace a data field across all layers
.github/skills/codebase-navigator/scripts/trace.sh data-flow <field_name>

# List all middleware
.github/skills/codebase-navigator/scripts/trace.sh middleware

# Trace state management for a key
.github/skills/codebase-navigator/scripts/trace.sh state <key>

Direct Ripgrep Patterns

When scripts don't cover your need:

# Find any symbol
rg --no-heading -n '\bMySymbol\b' apps/

# Python functions
rg --no-heading -n '(def|async def) my_function' apps/backend/ --type py

# React component usage
rg --no-heading -n '<MyComponent' apps/frontend/ --glob '*.tsx'

# Pydantic models
rg --no-heading -n 'class My.*BaseModel' apps/backend/ --type py

# API routes
rg --no-heading -n '@(router|app)\.(get|post|put|patch|delete)' apps/backend/ --type py

Architecture Docs

Need	Document
Backend architecture	docs/agent/architecture/backend-architecture.md
Frontend architecture	docs/agent/architecture/frontend-architecture.md
API contracts	docs/agent/apis/front-end-apis.md
API flow maps	docs/agent/apis/api-flow-maps.md
Full doc index	docs/agent/README.md

Project Layout

apps/
├── backend/app/
│   ├── main.py              # FastAPI entry, CORS, routers
│   ├── config.py            # Pydantic settings from env
│   ├── database.py          # TinyDB wrapper
│   ├── llm.py               # LiteLLM wrapper (multi-provider AI)
│   ├── routers/             # API endpoint handlers
│   ├── services/            # Business logic layer
│   ├── schemas/             # Pydantic request/response models
│   └── prompts/             # LLM prompt templates
│
└── frontend/
    ├── app/                 # Next.js pages (dashboard, builder, tailor, print)
    ├── components/          # Reusable UI components
    ├── lib/                 # API client, utilities, i18n
    ├── hooks/               # Custom React hooks
    └── messages/            # i18n translations (en, es, zh, ja)

Key Entry Points

What	File
Backend startup	apps/backend/app/main.py
Frontend pages	apps/frontend/app/
API client	apps/frontend/lib/api.ts or lib/api-client.ts
Design tokens	apps/frontend/app/globals.css
Resume schemas	apps/backend/app/schemas/
LLM prompts	apps/backend/app/prompts/

Reference

See references/REFERENCE.md for the full ripgrep cheat sheet and advanced patterns.