Codebase Navigator

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

Quick Start

Search scripts (preferred)

Run the bundled scripts for common searches:

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

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

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

# Trace an API flow end-to-end
.agents/skills/codebase-navigator/scripts/trace.sh api-flow <endpoint>

# Trace a data field from backend to UI
.agents/skills/codebase-navigator/scripts/trace.sh data-flow <field_name>

# Find component hierarchy
.agents/skills/codebase-navigator/scripts/trace.sh component-tree <ComponentName>

Direct ripgrep patterns

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

# Python function definitions
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 route handlers
rg --no-heading -n '@(router|app)\.(get|post|put|patch|delete)' apps/backend/ --type py

Architecture Overview

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
│   ├── routers/             # API endpoints
│   ├── services/            # Business logic
│   ├── schemas/             # Pydantic models
│   └── prompts/             # LLM prompt templates
│
└── frontend/
    ├── app/                 # Next.js pages
    ├── components/          # UI components
    ├── lib/                 # API client, utilities, i18n
    ├── hooks/               # Custom React hooks
    └── messages/            # i18n translations (en, es, zh, ja)

Common Workflows

"Where is X defined?"

.agents/skills/codebase-navigator/scripts/search.sh functions my_function
.agents/skills/codebase-navigator/scripts/search.sh components MyComponent
.agents/skills/codebase-navigator/scripts/search.sh classes MyClass
.agents/skills/codebase-navigator/scripts/search.sh types MyType

"What calls X?"

.agents/skills/codebase-navigator/scripts/search.sh usage my_function
.agents/skills/codebase-navigator/scripts/search.sh deps my_file.py

"How does data flow for feature X?"

.agents/skills/codebase-navigator/scripts/trace.sh api-flow resumes
.agents/skills/codebase-navigator/scripts/trace.sh data-flow personalInfo
.agents/skills/codebase-navigator/scripts/trace.sh component-tree ResumeEditor

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 search patterns.