sz
中文
← Writing

Ramping Up on a New Codebase

May 2022 · 2 min read

Joining a new codebase is an exercise in controlled breadth-first search. The mistake most engineers make on day one is diving into a single service and losing the map.

Strategy: understand each project and how they relate at a high level. Do not deep-dive on day one.

Locate the anchors first

Before reading code, find:

  • Git repositories (mono vs multi-repo)
  • Environments — dev, staging, production — and who deploys where
  • Wiki, README, architecture docs (even if stale)
  • CI pipelines and what they gate
  • Entry URLs, admin panels, database hosts (read-only access)

If any of these don't exist, that's your first signal about organizational maturity.

Phase 1: Trace the data path

Follow one user-visible flow end to end:

Browser URL → frontend → API → backend service → database

Click through lightly. Note what the user sees vs what the API returns. Mark which host runs which service. You are building a living diagram, not memorizing files.

Phase 2: Data model

Most business systems are CRUD with extra steps. Find:

  • Core tables and entities
  • Relationships (one-to-many, soft deletes, versioning)
  • Which service owns which schema

ORM models, migration folders, and ER diagrams (if they exist) are your friends here.

Phase 3: Code patterns

Business logic usually falls into three buckets:

  1. Interactive CRUD (HTTP handlers, validation, persistence)
  2. Batch jobs and scripts (cron, queues, ETL)
  3. Cross-service calls (RPC, events, webhooks)

Identify which bucket your assigned area lives in before optimizing anything.

Phase 4: API workflows

Practical tactics:

  • Save Postman (or Bruno) collections with success and failure examples
  • Batch-test endpoints to find undocumented edge cases
  • Generate or update API docs for frontend consumers
  • Mock unfinished endpoints so UI work isn't blocked

Draw state diagrams for multi-step flows. Map each API call to table mutations.

Phase 5: System boundaries

Zoom out again:

  • Message queues — who produces, who consumes, what happens on retry?
  • Infer service graphs from API names and shared libraries
  • Ask in standup or 1:1s: what hurts right now? Pain points prioritize reading order

Only then go deep on your assigned module — and schedule regular zoom-outs so you don't become a local maximum expert in one folder.

Reference: Onboarding guide (flashsun)