How to Read an Existing Frontend System
Why this chapter matters
Architects are often dropped into systems that already exist. Before changing anything, you need to read the system: its user journeys, boundaries, data flows, runtime costs, ownership model, and failure behavior.
The reading sequence
What to inspect first
| Layer | What to look for |
|---|---|
| product journey | critical paths, conversion points, recovery paths |
| routes | route ownership, rendering mode, auth boundaries, layout shells |
| data | API contracts, cache layers, stale data behavior, error shapes |
| state | global stores, URL state, local state, optimistic updates |
| modules | import graph, package boundaries, shared utilities, cycles |
| runtime | bundle chunks, long tasks, hydration, memory leaks |
| quality | tests, accessibility checks, budgets, observability |
| operations | incidents, alerts, flags, rollback procedures |
System reading artifacts
Produce four artifacts before proposing a large change:
| Artifact | Purpose |
|---|---|
| route inventory | identifies surfaces, owners, rendering strategy, and risk |
| data ownership map | shows authoritative sources, caches, invalidation, and sensitivity |
| dependency graph | exposes coupling, cycles, shared packages, and migration constraints |
| quality signal map | shows what production can and cannot explain |
Red flags
- No one can name the owner of a critical route.
- Shared utilities contain product-specific business behavior.
- Server data is copied into global state without invalidation rules.
- Routes have no explicit loading, empty, error, or degraded states.
- Performance is measured only by local Lighthouse runs.
- Third-party scripts lack owner, purpose, and data classification.
- Incidents repeat because architecture decisions are undocumented.
Review checklist
- Have you mapped the user journey before reading code?
- Can you explain rendering and data flow for the critical route?
- Can you name the highest-coupled modules?
- Do production signals explain the most likely failures?
- Is your proposed change grounded in observed system structure?
Exercises
- Create a route inventory for an app you maintain.
- Draw the data ownership map for one critical workflow.
- Find one module boundary that hides an ownership problem.
- Identify one production failure that current telemetry cannot explain.
Source lens
Use this chapter before Part IV modularity, Part VI performance incident response, Part VIII reliability/security work, and Part XI case studies.