Step 2 · Explore the Codebase

Goal

Build a mental model of the codebase — its structure, conventions, critical paths, and where things live — so you can make changes confidently without breaking things you didn't intend to touch.

Instructions

You are in workflow step 2 of the onboarding-cycle. The environment is running. Your job is to understand the codebase at a structural level before writing any code.

Tasks to Perform

1. Map the Structure

# High-level structure
tree -L 3 --gitignore 2>/dev/null || find . -maxdepth 3 -not -path "*/node_modules/*" \
  -not -path "*/.git/*" -not -path "*/vendor/*" -not -path "*/dist/*" | sort

# Count lines of code by language
find . -name "*.{php,js,ts,py,rb,go,java,cs}" \
  | grep -v node_modules | grep -v vendor | grep -v ".git" \
  | xargs wc -l 2>/dev/null | sort -n | tail -30

2. Find the Entry Points

# Web entry points
grep -rn "listen\|app.listen\|->run\|start_server\|serve" \
  --include="*.{php,js,ts,py,go,rb}" . \
  | grep -v node_modules | grep -v vendor | head -20

# CLI entry points
find . -name "*.php" -path "*/bin/*" -o -name "*.py" -path "*/bin/*" \
  -o -name "Makefile" | grep -v vendor | grep -v node_modules | head -10

# Routes / controllers
find . -name "routes*.php" -o -name "routes*.ts" -o -name "routes*.js" \
  -o -name "*.routes.ts" -o -path "*/controllers/*" \
  | grep -v node_modules | grep -v vendor | head -20

grep -rn "Route::\|router\.\|createRouter\|app.get\|app.post" \
  --include="*.{php,js,ts}" . | grep -v node_modules | grep -v vendor | head -30

3. Understand the Data Model

# Find schema definitions
find . -name "schema.prisma" -o -name "schema.rb" \
  -o -name "*migration*" -type f | grep -v node_modules | grep -v vendor | head -20

# Find model/entity classes
find . -path "*/models/*.{php,py,rb,ts}" \
  -o -path "*/entities/*.{php,ts}" \
  -o -path "*/domain/*.{php,ts}" \
  | grep -v node_modules | grep -v vendor | head -30

# Database tables and relationships
psql $DATABASE_URL -c "\dt" 2>/dev/null

4. Trace a Request End-to-End

Pick the most important feature and follow a single request through the system:

# Find the route handler for, e.g., "orders" feature
grep -rn "orders" --include="*.{php,js,ts,py,rb}" . \
  | grep -E "route|Route|router\.|@(Get|Post|Put|Delete)" \
  | grep -v node_modules | grep -v vendor | head -20

# Read: Route → Controller → Service → Repository/Model → Database
# Do not skip any layer

Document the request path in docs/architecture/request-flow.md.

5. Find the Test Suite

# Test file locations
find . -name "*.test.{js,ts,php,py,rb}" -o -name "*_test.go" \
  -o -name "*_spec.rb" -o -name "test_*.py" \
  | grep -v node_modules | grep -v vendor | head -30

# Test configuration
cat jest.config.js 2>/dev/null
cat phpunit.xml 2>/dev/null
cat pytest.ini 2>/dev/null
cat .rspec 2>/dev/null

# Coverage
npm test -- --coverage 2>/dev/null   | grep "All files"
php artisan test --coverage 2>/dev/null | tail -5
pytest --co -q 2>/dev/null | tail -5

6. Understand the Conventions

# Code style configuration
cat .eslintrc* 2>/dev/null
cat phpcs.xml 2>/dev/null
cat .rubocop.yml 2>/dev/null
cat pyproject.toml 2>/dev/null | grep -A 20 "\[tool.ruff\]"

# Git conventions
cat .gitmessage 2>/dev/null
git log --oneline -15   # see the commit message style in use

# PR / contribution process
cat CONTRIBUTING.md 2>/dev/null | head -60

7. Identify the Critical Paths

The "critical path" is the code that: handles money, stores user data, controls access, or is called by every request.

Flag these files in your docs/architecture/critical-paths.md:

Authentication / authorisation
Payment processing
Data storage (DB write paths)
Public API endpoints (highest traffic)
Background job processing

8. Document What You Learned

Create a brief architecture doc if one doesn't already exist:

# Create docs/architecture/overview.md with:
# - Tech stack
# - Top-level architecture (request flow diagram if complex)
# - Key services and their responsibilities
# - Where to find things (routing, models, tests, config)
# - Conventions to follow

Add to TODO.md:

- [x] Explore codebase structure and conventions _(ref: workflows/onboarding-cycle/02-explore-codebase.md)_
- [ ] Write architecture overview doc _(ref: workflows/onboarding-cycle/02-explore-codebase.md)_

Exit Criteria

[ ] Can describe the top-level structure without looking at it
[ ] Can trace a request from HTTP to database for the main feature
[ ] Knows where tests are and how to run them
[ ] Understands code style and git conventions
[ ] Architecture overview document exists (or created)
[ ] Critical paths identified

Next Step

→ Proceed to Step 3 · First Contribution