Method
How I enter an unfamiliar backend.
The riskiest moment in contract work is the first week in someone else’s system: the code is load-bearing, the documentation may not match it, and the person who knew why things are the way they are may be gone. This is what I do in that week — the same method for a bug fix or a full takeover, only the depth changes.
- trace one real request
- find the real boundaries
- walk the failure paths
- ask the 2am question
- read the data's history
- one small tested change
The order is the point: understand before touching, cheapest checks first.
Trace one real request, end to end.
I pick the flow you actually care about — the order that duplicates, the report that fails — and read it from HTTP entry to the database and back. Not the folder structure: the actual call path. Folders say what the architecture intended; the trace says what it does, and the two disagree more often than anyone admits.
Find where the boundaries actually fall.
Which layer decides validity, which component owns each table, where transport concerns have leaked into business logic. A change made on the wrong side of a boundary works in the demo and breaks in production — mapping the real seams first is what makes every later change cheaper and safer.
Walk the failure paths.
Retries, timeouts, partial failures, idempotency: one consistent policy, or improvised per endpoint? This is where small backends quietly become hard to maintain, and where money paths hide their worst bugs — a retry without an idempotent write is a duplicate charge waiting for a network blip.
Ask whether the logging answers the 2am question.
Logging that exists is not logging that helps. When this flow fails at 2am, do the logs say which request, which state, which decision? If not, that is usually the first cheap improvement — it pays for itself during the rest of the engagement.
Read the data model and its migration history.
The schema’s history explains most of the code’s oddities: the renamed column, the nullable that shouldn’t be, the table nobody dares drop. It is also where the risk concentrates — code reverts cleanly; data mistakes don’t.
Only then, change something — small, tested, reversible.
The first change is a bounded slice with a test proving it, never a refactor. You see the result, plus a short written note — what to leave alone, what is worth changing now, what can wait — before committing to anything larger.
What this costs.
For a trivial script this ceremony is overkill — I skip it and say so. And I don’t recommend rewrites from first impressions: a rewrite recommendation needs evidence that the current design fails under its real load, and first weeks rarely produce that evidence honestly.
Deeper: how I work with the person who owns the product · a real system map · design decisions with their costs