Prompt Engineering

Architecture Explanation Prompt — Layers, Boundaries, Data Flow

Explain a system's shape, not its statements: layers and their owners, boundary contracts, dependency direction, and one request traced through every handoff.

Open in Code Explanation Prompt

Overview

Architecture explanations fail when they describe files instead of structure. This prompt uses the architecture mode's strategy: identify the layers and the responsibility each owns, trace what each module exposes and hides, map dependency direction explicitly — flagging cycles and inversions — and follow the data through every boundary. The senior-developer audience keeps it at rationale level: why the boundaries sit where they sit, what changes together, what the isolation buys. The learning note demands the one-paragraph summary a new architect could repeat — shape, key boundaries, and the one rule never to break.

How to use this resource

Name the layers and owners

Each module gets a one-line responsibility — structure first, files second.
Map direction, flag cycles

What depends on what is stated explicitly; cycles and inversions are findings of fact, not judgments.
Trace one real request

A representative request walks every layer, naming each handoff — the shape becomes concrete.

Why This Works

Dependency direction is checkable; "the architecture" as vibes is not
One traced request makes abstract boundaries concrete
The repeatable one-paragraph summary is what survives the meeting

Best for

Systems whose architecture grew rather than was designed
Design review preparation
Senior engineers inheriting a system

Not for

Fixing the boundaries it describes — that's the Refactor Prompt Builder's Architecture Cleanup goal
Judging whether the architecture is good — that's the Code Review Prompt Generator's architecture focus

Use cases

Preparing the current-state picture before a design review
Explaining why module boundaries sit where they sit
Tracing one request through every layer it touches

FAQ

Does the architecture explanation prompt tell me whether my boundaries are good or bad?

It explains, it does not judge. The NON-GOALS forbid it: "Do not review code quality — no findings, no severities, no verdicts." The EXPLANATION STRATEGY maps layers, boundary contracts, and dependency direction — flagging cycles and inversions as facts, not judgments — so you get the current-state shape for a design review, with the quality call left to you.

How does this prompt keep the AI from inventing rationale it can't see in the code?

The ASSUMPTIONS section forces separation: every statement about intent, history, or rationale must be labeled an INFERENCE unless the code evidences it via a comment, test, or telling name, and where behavior is unknowable it must say "cannot be determined from this code" rather than fill the gap with a plausible story. The output ends with open questions for the team.

Why is this architecture prompt aimed at a senior developer instead of a beginner?

The AUDIENCE PROFILE assumes anything readable from the code is already understood and spends the explanation on "why this design, what constraints shaped it, where it is fragile" — explicitly not walking the code line by line. That calibration is why it traces one representative request through every boundary and produces a one-paragraph summary a new architect could repeat, rather than narrating statements.

Customize This Resource

Opens this setup in Code Explanation Prompt. Generate to get the full understanding contract — then adjust the mode, audience, and depth.

Open in Code Explanation Prompt

Prompt Template

Copy it as-is, or use Open in Code Explanation Prompt to load it pre-filled and customize it with your own context.

EXPLANATION OBJECTIVE
Explain the current architecture of the notification service ahead of the design review.
Explanation mode: architecture explanation — layers, boundaries, dependencies, and data flow.
The goal is understanding, not judgment: explain what this code does and why it is built this way — and clearly separate what the code shows from what you infer.

CODE CONTEXT
System context: Handles email, SMS, and push; suspected of having grown unclear boundaries between channel logic and delivery logic.
Code to explain:
```
[Paste the code to explain here]
```

AUDIENCE PROFILE
Audience: a senior developer — reads code fluently and wants rationale, not narration.
- Assume: anything readable from the code is already understood.
- Spend the explanation on what the code cannot say: why this design, what constraints shaped it, where it is fragile.
- Do not walk the code line by line — that would waste this reader's time.

EXPLANATION STRATEGY
1. Identify the layers or modules and the responsibility each one owns.
2. Trace the boundaries: what each module exposes, what it hides, and which contracts cross the lines.
3. Map dependency direction explicitly — what depends on what, and flag any cycles or inversions.
4. Follow the data: how information enters, how it transforms at each boundary, and where it ends up.
- Depth: detailed explanation — thorough coverage of behavior and structure.
- Cover every section of this contract with real content — no skipped or token sections.
- Go as deep as the code requires, but no deeper: detail serves understanding, not completeness theater.

KEY CONCEPTS
- Define the architectural vocabulary in use — the layer names, the patterns, the conventions this structure relies on.
- Order concepts by how load-bearing they are for understanding this code — not by where they appear in the file.

EXECUTION FLOW
- Trace one representative request or data item through every layer it touches, naming each handoff.
- Where the flow depends on state or configuration, say which, and what each setting changes.

DESIGN DECISIONS
- Explain why the boundaries sit where they sit: what changes together, what is isolated from what, and what that isolation buys.
- Discuss only decisions actually visible in the code; rationale you cannot evidence belongs under ASSUMPTIONS, labeled as inference.

ASSUMPTIONS
- Separate what the code DOES (verifiable from the source) from why it might be that way (inference).
- Label every statement about intent, history, or rationale as an INFERENCE unless the code itself evidences it — a comment, a test, a telling name.
- Where behavior cannot be determined from the provided code, say "cannot be determined from this code" — never fill the gap with a plausible story.

TRADEOFFS
- Identify the tradeoffs this code embodies: what it optimizes for, and what it sacrifices for that.
- Tie each tradeoff to its visible consequence in the code.

LEARNING NOTES
- Summarize the architecture in one paragraph a new architect could repeat — the shape, the key boundaries, and the one rule never to break.

NON-GOALS
- Do not review code quality — no findings, no severities, no verdicts.
- Do not debug failures — explain the behavior that exists without diagnosing it.
- Do not refactor the code or propose rewrites.
- Do not generate tests.
- Do not invent requirements or unstated intentions.
- If something looks defective, note it as a question for the team — investigating or fixing it is out of scope.
- Clearly separate facts from assumptions throughout.

OUTPUT REQUIREMENTS
- Structure the explanation with headings that mirror the sections above — a reader should be able to navigate it without reading all of it.
- Anchor every claim about behavior in the code: name the function, branch, or line it comes from when precision matters.
- Calibrate every section to the stated audience — too basic wastes their time, too advanced loses them.
- End with the open questions: what could not be determined from the provided code, and who or what could answer it.

More resources from Code Explanation Prompt

Resource

Explain Code Prompt — the Understanding Contract

"Explain this code" gets line-by-line narration. The understanding contract gets strategy, audience-fit, design decisions, and inference labeled as inference.

Prompt Engineering

Resource

Legacy Code Analysis — Likely Intent, Hidden Assumptions

For code whose authors are gone: reconstruct likely intent as labeled inference, hunt undocumented assumptions, and end with a maintenance brief — what's safe to touch.

Prompt Engineering

Resource

Algorithm Explanation Prompt — Idea, Steps, Complexity, Tradeoffs

Explain the idea before the implementation: numbered steps with their contribution, honest best/worst-case complexity, and the alternatives each decision point rejected.

Prompt Engineering

Resources that pair well

Resource

Code Review Prompt — the Review Contract

"Review this code" gets shallow comments. The review contract gets findings with severities, a checklist, and a verdict.

Prompt Engineering

Resource

Refactor Prompt — the Behavior Preservation Contract

"Refactor this code" invites silent behavior changes. The refactoring contract preserves business rules, outputs, and side effects — and flags uncertainty instead of deciding it.

Prompt Engineering

Resource

Debugging Prompt — the Investigation Contract

"Fix this error" gets guesses. The investigation contract gets a ten-stage diagnosis: facts separated from assumptions, alternatives weighed, fixes justified.

Prompt Engineering

Related tools

Tool

Code Explanation Prompt

Build code explanation prompts — mode, audience, and depth turn into an understanding contract that teaches, not narrates.

Coding Workflows

Projects that use this resource

Project

Modernize a Legacy Codebase with AI

The full path to taming an inherited codebase — understand it, document its architecture, pin its behavior with tests, then refactor, modernize, review, speed up, and ship it without breaking what works.

8 stages Software Development

Workflows that use this resource

Workflow

AI Architecture Recovery Workflow

Recover a legacy system's architecture before you change it — package the codebase context, explain the current structure, surface the risks and seams, then document the recovered architecture.

4 steps 40–70 minutes

Guides for this resource

Guide

Get AI to Explain a Codebase for Onboarding

Ask AI to "explain this codebase" and you get generic architecture and "read the controllers" — no reading order, no flow, nothing to act on. Here's how to explain a codebase for onboarding: a map of folders and flow, a reading path, safe first tasks, and the unknowns to confirm.

Software Development with AI

Guide

How to Document System Architecture With AI

The new engineer asks how the system actually works and gets a whiteboard photo from two years ago, or an AI answer that confidently names a queue that isn't there. Here is how to document system architecture with AI: the current state, with every component traced to a fact or marked unconfirmed.

Software Development with AI

Tip: Save time by exploring related resources and tools that integrate with this resource.