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
./scripts/search.sh functions <pattern>

# Find React components
./scripts/search.sh components <pattern>

# Find API endpoints
./scripts/search.sh endpoints

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

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

# Find component hierarchy
./scripts/trace.sh component-tree <ComponentName>

Scripts are at: .agents/skills/codebase-navigator/scripts/

Direct ripgrep patterns

When you need something the scripts don't cover:

# 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'

# Type definitions
rg --no-heading -n '(type|interface) MyType' apps/frontend/ --glob '*.ts'

# 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

# Imports of a module
rg --no-heading -n 'from.*my_module.*import|import.*my_module' apps/

Architecture Overview

Read these docs for full understanding:

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 endpoints
│   │   ├── config_router.py # GET/PUT /api/v1/config
│   │   ├── health_router.py # GET /api/v1/health
│   │   ├── resume_router.py # CRUD /api/v1/resumes
│   │   └── jobs_router.py   # CRUD /api/v1/jobs
│   ├── services/            # Business logic
│   │   ├── parser.py        # Resume parsing
│   │   └── improver.py      # AI resume improvement
│   ├── 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)

Common Search Workflows

"Where is X defined?"

./scripts/search.sh functions my_function
./scripts/search.sh components MyComponent
./scripts/search.sh classes MyClass
./scripts/search.sh types MyType

"What calls X?"

./scripts/search.sh usage my_function
./scripts/search.sh deps my_file.py

"How does data flow for feature X?"

./scripts/trace.sh api-flow resumes
./scripts/trace.sh data-flow personalInfo
./scripts/trace.sh component-tree ResumeEditor

"What API routes exist?"

./scripts/search.sh api-routes

"What environment config is used?"

./scripts/search.sh config

"What needs fixing?"

./scripts/search.sh todos

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/

Tips

• Always check docs/agent/ before deep-diving into code
• Use rg --type py for Python, rg --glob '*.tsx' for React components
• When tracing a feature, start from the API route and follow imports
• Check apps/frontend/components/ for reusable UI patterns
• Check apps/backend/app/services/ for business logic