System Overview — first-pass orientation for an unfamiliar codebase

SYSTEM_OVERVIEW.md

Before You Start

• Root

  README.md

  — the project's own framing. Match its vocabulary.
• Root

  CLAUDE.md

  (or

  AGENTS.md

  ) — repo-specific guardrails the human authors put down.
• Top-level entry points —

  main.py

  ,

  app/

  ,

  src/index.ts

  ,

  cmd/

  ,

  Dockerfile

  ,

  docker-compose.yml

  . Read them before claiming what the system is.

Step 1: orient with the file tree

tree -L 2 -I 'node_modules|.git|.venv|__pycache__|dist|build'
find . -maxdepth 2 -name 'README*' -not -path '*/node_modules/*'

pyproject.toml

package.json

go.mod

Cargo.toml

pom.xml

Step 2: locate the entry points and external boundaries

# HTTP / RPC entry points
grep -rln "FastAPI\|express()\|http.HandleFunc\|@RestController\|@SpringBootApplication" \
  --include='*.py' --include='*.ts' --include='*.js' --include='*.go' --include='*.java' .

# External integrations (DB, cache, queues, third-party APIs)
grep -rEn "psycopg|sqlalchemy|redis|kafka|amqp|boto3|requests\.|httpx\.|fetch\(" \
  --include='*.py' --include='*.ts' --include='*.js' . | head -30

Step 3: write

SYSTEM_OVERVIEW.md

with the canonical structure

# System Overview

> Audience: a senior engineer new to this system. Drafted by an LLM, requires human review.

## CORE ANALYSIS (Required)

- Tools, frameworks, and design patterns used across the repository
- Data models and API design
- Mermaid architecture diagram of the system and its dependencies at a high level

## SYSTEM DESIGN (Required)

- File-by-file explanation of the central modules and how they link
- Mermaid sequence diagram for the primary data flow
- Mermaid flowcharts for any complex branching flows

## LEGACY ASSESSMENT (If applicable)

- Inconsistencies in architectural patterns
- Deviations from language or framework conventions
- Distinctions between old and new architectural approaches

Optional extensions (lecture-specific, not in the source prompt)

• Cross-cutting concerns — auth, logging, config, error handling — one paragraph each, with file references.
• Technical-concern hotspots — files or modules with high churn, high cyclomatic complexity, or long-standing TODOs.
• Open questions for human architects — the things you could not determine from the code alone. List them; do not guess.
• Citations rule. Every claim cites at least one

  path/to/file.ext:line

  reference.
• UNVERIFIED tag. Any inference not directly supported by a file you read is prefixed

  UNVERIFIED:

  so reviewers can triage.

Step 4: anchor every claim to a file

EventBus.publish

app/events/bus.py:42

app/events/registry.py:18-31

UNVERIFIED:

Step 5: render and sanity-check the Mermaid

# If mmdc is available
npx -y @mermaid-js/mermaid-cli -i SYSTEM_OVERVIEW.md -o /tmp/overview.svg

Verify

• SYSTEM_OVERVIEW.md

  exists at the repo root.
• All three required sections (

  CORE ANALYSIS

  ,

  SYSTEM DESIGN

  ,

  LEGACY ASSESSMENT

  ) are present.
• At least one Mermaid block parses.
• Every assertion has a file reference, or is prefixed

  UNVERIFIED:

  .
• The first paragraph names the language, framework, and primary external dependencies.

Common Mistakes

• Claiming patterns from file names. A file called

  repository.py

  may not implement the Repository pattern. Open it. If you cannot verify, write

  UNVERIFIED:

  .
• A flat module list pretending to be an architecture. Sequence and dependency between modules is the value; the list is not. Add at least one Mermaid diagram showing edges.
• Skipping the

  LEGACY ASSESSMENT

  because the code "looks fine." If you found zero inconsistencies in 30 minutes of reading, you read too quickly. Cite the conventions you checked against, even if the verdict is "consistent."
• Embellishing past the source prompt without flagging it. If you add the optional extensions (hotspots, open questions, UNVERIFIED rule), say so in the document header so reviewers know which sections are the canonical Sumner/Chesser shape and which are local additions.