Explain Architecture

Explain Architecture

Build an accurate mental model of a codebase (or a chosen part of it) and explain it clearly. The goal is orientation, not critique — a reader should finish knowing what the pieces are, how they fit, where data flows, and where to look next.

Borrowed from Practical Model-Driven Enterprise Architecture: an explanation is a view that answers a defined question for a defined audience, split into structure (what the parts are and how they connect) and behavior (what happens, in what order). Pick the scope and audience first, then explain only what serves them — "a single view tells a single idea."

Step 0 — Scope & audience (ask only if unclear)

Settle two things before exploring; infer from the request when you can, ask at most one short question when you can't:

• Scope — whole repo, one service, one feature/flow, or one module.
• Audience / depth:
• Newcomer — onboarding overview, minimal jargon, "where do I start".
• Implementer — enough to add a feature here: extension points, conventions, gotchas.
• Reviewer — boundaries, dependencies, invariants, risk areas.

Default to newcomer + whole-repo overview if the user just says "explain the architecture" with no qualifier.

Once audience is fixed, read references/viewpoints.md for that viewpoint's template and length guidance before exploring. If working in greenspark-aws, also read references/greenspark.md for the known service map, seam inventory, and layer mapping.

Step 1 — Explore (don't guess)

Ground every claim in files you actually read. Move outside-in:

1. Entry points & manifests — package.json/workspaces, template.yaml/SAM, CLAUDE.md files, READMEs, docs/, config. These declare intent cheaply. 2. Top-level structure — map the directory tree to responsibilities. Name each major unit and its one-line job. 3. The seams — how units communicate: HTTP routes, message buses/events, shared data layer, cron/workers. The seams are the architecture. 4. One real flow end-to-end — trace a representative request or event through the layers (e.g. frontend action → API route → service → entity/DB → emitted event → worker). A concrete trace beats abstract description. 5. Cross-cutting — auth, multi-tenancy, error handling, migrations, codegen.

Use Explore/general-purpose subagents for breadth on large scopes so you keep only the conclusions, not the file dumps. Cite findings as file:line.

Step 2 — Organize into layers

Group components into the three layers (from the book), so the reader sees order, not a list:

• Business — domain rules & invariants.
• Application — software automating the domain: services, routes, workers, the

frontend app.

• Technology — infra plumbing: cloud runtime, database, auth, build/deploy.

Derive the layers from what you actually find rather than forcing these names. (For greenspark-aws, use the layer mapping in references/greenspark.md.)

Step 3 — Explain (output)

Tune length to audience. Lead with the big picture, then drill down. Use this skeleton:

## Architecture: <scope>

### In one paragraph
<what this system is and the single organizing idea — e.g. "event-driven serverless
monorepo, org-scoped multi-tenant, OpenAPI-first frontend">

### The pieces (structure)
- **<component>** (`path/`) — <one-line job>. Talks to: <neighbors>.
- ...

### How it fits together
<the seams: how components communicate, dependency direction, the layer story>

### A flow end-to-end (behavior)
1. <step> (`file:line`)
2. ...
<one concrete request/event traced through the layers>

### Cross-cutting concerns
<auth, multi-tenancy, migrations, codegen — only what's relevant to the scope>

### Where to look next
<the 3–5 files/dirs the reader should open first for their goal>

Rules from the book's "modeling best practices", applied to prose:

• One idea per explanation. If two subsystems each need a full treatment, say so and

offer to explain the second separately rather than tangling them.

• Only necessary detail for the audience — a newcomer doesn't need every Lambda; a

reviewer does need the boundaries.

• Name things with the codebase's own vocabulary (its taxonomy), not invented terms.
• Don't editorialize. Note a smell in one line if it blocks understanding, but routing

a quality verdict is architecture-lens's job, not this skill's.

Step 4 — Offer a diagram (don't auto-generate)

After the written explanation, offer a visual if it would help:

• A quick Mermaid block inline for most cases — a component graph (graph LR) for

structure, sequenceDiagram for a flow.

• For a polished standalone artifact, suggest visual-explainer:generate-web-diagram or

visual-explainer:project-recap (the latter when they want the broader "state of the project" rather than a pure structure diagram).

Only produce the diagram if the user wants it — keep the default response readable text.

Explain Architecture — greenspark-aws reference

Read this when the scope is the greenspark-aws repo (or one of its services). It holds the known service map, seam inventory, layer mapping, and a worked example for that codebase.

Service map (Step 0 scope options)

One service means one of: core-api, dispatch, eda-worker, erp-sync-workflow, frontend, common/gslogic.

Seam inventory (Step 1)

• The seams — how units communicate: HTTP routes, EventBridge events, shared

common entities/TypeORM, RTK Query API layer, cron/workers.

• A representative flow — e.g. frontend action → API route → service → entity/DB →

emitted event → worker.

• Cross-cutting — auth, multi-tenancy (org-scoping), error handling, migrations,

codegen (OpenAPI → RTK Query).

Layer mapping (Step 2)

• Business — domain rules & invariants: backend/common entities/domain, gslogic.
• Application — software automating the domain: core-api routes & services,

dispatch, eda-worker, erp-sync-workflow, compliance, pdf-generator, frontend RTK/API layer & React app.

• Technology — infra plumbing: AWS SAM/Lambda/EventBridge/S3, Postgres/TypeORM,

Amplify auth, Vite build/deploy.

Worked example — whole-repo, newcomer viewpoint

In one paragraph. greenspark-aws is a multi-tenant scrap-metal recycling platform: a

React/Vite frontend and a serverless AWS backend (SAM) split into domain services that

communicate over EventBridge. All data is org-scoped (multi-tenant). The frontend's API

layer is generated from the backend's OpenAPI schema, so types flow backend → frontend

automatically.

>

The pieces.

- frontend/client — React 17 + MUI + Redux Toolkit app; API calls via generated RTK

Query endpoints.

- backend/core-api — main REST API, business logic by domain.

- backend/common — shared TypeORM entities & utilities (the data model).

- backend/eda-worker — event-driven processing off EventBridge.

- backend/dispatch, erp-sync-workflow, compliance, pdf-generator — domain

services for assets, ERP integration, regulatory reporting, documents.

>

How it fits together. Frontend → core-api over HTTP; services emit/consume

EventBridge events; everything shares the common entities and one Postgres DB; the

frontend's typed client is regenerated from core-api's OpenAPI schema (`npm run

generate:api`).

>

A flow end-to-end. (trace a real request through route → service → entity → emitted

event → worker, with file:line cites)

>

Where to look next. Root CLAUDE.md, backend/CLAUDE.md, frontend/CLAUDE.md, then

backend/core-api routes for the domain you care about.

(Replace the flow section with an actual traced request when running the skill — don't ship the placeholder.)

Explain Architecture — viewpoints, templates & examples

A viewpoint (from Practical Model-Driven Enterprise Architecture, Ch 5) names who the explanation is for and what concern it answers. Same codebase, different viewpoint = different explanation. Pick one; don't blend three audiences into one wall of text.

---

Viewpoint: Newcomer (onboarding)

Concern: "What is this, and where do I start?"

• Lead with the one-paragraph identity and the single organizing idea.
• Name the 5–8 top-level units, one line each. Skip internal detail.
• Trace ONE happy-path flow so they see the pieces move.
• End with "open these 3 files first."
• Minimize jargon; expand acronyms once.

Length: short. They will get lost in completeness — give them a map, not the territory.

Viewpoint: Implementer (adding a feature)

Concern: "How do I add X without fighting the codebase?"

• Show the conventions: where routes/services/entities/components go, naming, the codegen

step (OpenAPI → RTK Query), how migrations are created/run.

• Show the extension points for the area they're touching.
• Call out gotchas: org-scoping, event contracts, shared common types, feature flags.
• Trace the flow of the kind of thing they're adding (a new endpoint, a new event

consumer), not a random one.

Length: medium, concrete, example-driven.

Viewpoint: Reviewer / architect

Concern: "Where are the boundaries, dependencies, and risks?"

• Emphasize dependency direction and layer boundaries (pairs well with architecture-lens).
• Surface invariants, multi-tenancy enforcement points, transaction boundaries, the

event-driven seams and their contracts.

• Note coupling hotspots and single-points-of-failure factually.
• A diagram earns its keep here.

Length: medium–long, precise.

---

Structure vs behavior (always cover both)

The book splits every system into two view types — explain both:

• Structural — the parts and their relationships (component map, dependency direction,

who-owns-what). Answers what exists.

• Behavioral — the sequence of what happens (request lifecycle, event flow, cron

cadence). Answers what happens, in what order.

A list of components without a flow leaves the reader unable to reason about runtime; a flow without the component map leaves them unable to locate code. Give both.

---

Worked example

For a full worked example (greenspark-aws whole-repo, newcomer viewpoint), see greenspark.md in this directory.

---

Boundaries with neighboring skills

• improve-codebase-architecture finds refactoring opportunities — not orientation.
• init generates a CLAUDE.md — use that if the user wants a committed doc; this skill is

for an in-session explanation (which can then feed init).