# Agent: Architecture (markdown detail)

| Field | Value |
| ----- | ----- |
| **AGENT_ID** | `ctx-md-architecture` |
| **Display name** | Architecture narrative |
| **SRS-8** | §4.2 `architecture.md`; §6.1 (parallel with global lists); **R7**, **R21** |
| **Output** | `<worktree>/.easyspecs/context/architecture.md` |
| **Pattern** | §3.5.1 — Markdown detail |

## Responsibility

**`.opencode/` and `.claude/` exclusion:** The worktree may contain **`.opencode/`** or **`.claude/`** (materialized coding agent definitions, schemas, and tooling). It is **not** part of the analyzed product codebase. **Do not** use it to infer application behavior. **Never** cite paths under **`.opencode/`** or **`.claude/`** in **`sourceReferences`**, UI/backend evidence arrays, Evidence index bullets, **`evidenceRefs`**, or any other code-grounding output.

Produce **application-wide** architecture narrative: components, boundaries, data flow, integrations, deployment view as appropriate. This is **not** the canonical feature list (that is `features-list.json`, §4.6).

**Mermaid is mandatory:** **`architecture.md` must contain at least one** fenced **Mermaid** diagram that reflects the real structure or behaviour of this codebase (not placeholder boxes). You **should** add **further** Mermaid diagrams wherever they improve clarity—e.g. separate views for **context vs internal components**, **request/sequence** paths, **state**, or **deployment**—without duplicating the same graph verbatim. **Target runtime:** **[MERMAID.md](./MERMAID.md)** — **Mermaid 11.13**, **neutral** theme (first line inside each fence: `%%{init: {'theme':'neutral'}}%%`).

## Implementation-only (SRS-114)

Document **only** what is **implemented in this repository today**. Do **not** add knowledge nodes for planned, missing, roadmap, or spec-only capabilities.

- **Include** a row or detail section **only** when you can cite **implementation evidence** (§3.1 in SRS-114): wired entrypoints, executable bodies, real UI artefacts, schemas in use, or behavioural tests (QA/TC).
- **Omit** the node entirely when you find only SRS, PLAN, README, comments, types without callers, empty stubs, or configs nothing reads.
- **`sourceReferences`** and **Evidence index** **must** include **at least one implementation anchor** (non-`.md` path per §5.6.2). **`.md`** files (SRS, README, plans) **may** be cited **in addition**, never as the **only** cites.
- **Review passes:** drop unimplemented rows like false rows; log **`droppedCodes`** / **`revisionLog`** (SRS-50).
- **Do not** fill coordination lists with placeholders for future work. An empty array is valid when nothing is implemented.


## Task (for `{{TASK_DESCRIPTION}}`)

Document how the system is structured and how major parts interact, grounded in the repository under **`{{WORKTREE_ROOT}}`**.

1. **Survey** entrypoints, packages, `src/` layout, configs, and integration boundaries so diagrams and prose match reality.
2. **Include `## Architecture diagrams (Mermaid)`** (see template) with **at least one** valid `mermaid` fenced block—typically a **component** or **system-context** view as **`flowchart`** / **`graph`** (layered boxes and edges that *read* like C4 are fine; **do not** use Mermaid **`C4Component`** or any other **`C4*`** diagram declaration—see **[MERMAID.md](./MERMAID.md)**). Prefer **node labels** that map to real modules, services, or deployable units.
3. **Add more diagrams** in that section or next to relevant headings (**Data flow**, **Context and boundaries**, etc.) when useful: e.g. `sequenceDiagram` for a critical path, `flowchart` for pipeline/steps, second graph for external dependencies. Each diagram should earn its place (no decorative noise).
4. Give each diagram a **short title** (heading or bold line above the fence) so readers can scan the doc.
5. **R21:** support diagram claims with **Evidence index** cites to the files that justify nodes and edges.
6. When applicable, fill **`## What kind of UI this is`** per **What kind of UI this is (when applicable)** below (table + non-UI callouts); otherwise omit or one line — never leave that heading empty without explanation.

## What kind of UI this is (when applicable)

When the codebase has an **operator or end-user UI** (not API-only or headless-only), add **`## What kind of UI this is`** to the generated `architecture.md`. Use a **compact table** so readers immediately see platform, framework, visual language, whether the product is one surface or many apps, and how UI ties to data if that matters. **Ground every row in Evidence index** cites (forms, project files, framework imports). If there is **no** meaningful UI, **omit** this section or use a single honest line under the heading (e.g. no operator UI; CLI/service only).

**Example** (shape and level of detail — **replace** with what the repo actually is; the rows below illustrate a classic Windows desktop / Delphi VCL operations suite):

| Aspect | Description |
|--------|-------------|
| **Platform** | Windows desktop (native Win32-style controls) |
| **Framework** | Embarcadero **Delphi VCL** (`TForm`, `TPanel`, `TTabSheet`, `TMainMenu`, etc.) |
| **Visual style** | Classic “business / operations” look: **MS Sans Serif** / **Microsoft Sans Serif**, `clBtnFace` backgrounds, raised/lowered panel bevels, **tabbed notebooks** and **data grids** |
| **Architecture** | Several **separate executables** (`.dpr`), each with its own windows — not a single web SPA |
| **Data binding** | Grids such as `TOrderDBGrid` tie to **data sources** (`TDataSource`) backed by the SQL Server database |

**Non-UI components:** Call out things that are **not** operator screens when they share the same repo — e.g. Windows **services** (`ReceptorSvc`, `ExportadorSvc`) that ship `.dfm` files for **service data modules**, not forms for users; **“No Service”** variants as small **program** windows that often **minimize to the system tray**. Adapt names and patterns to the actual codebase.

## Non-empty chapters and Evidence index (mandatory)

- **`## Evidence index`** is the **references / code-grounding** chapter. It **must not** be empty, whitespace-only, or placeholder-only (no bare `-`, no section with zero bullets). A generated `.md` with **no** substantive grounding bullets there is **invalid** and is **rejected**—do not produce that outcome.
- **Preferred:** at least one concrete `path:line` or `path:start-end` cite from the worktree (implementation, config, tests, schemas—not README-style narrative files).
- **If grounding is impossible** after reasonable search: set **`Status: hallucination?`** on its **own line immediately under the top-level `#` title**, **and** still add **at least one** Evidence index bullet describing what was searched, partial findings, and that claims are not implementation-backed.
- **Other `##` sections:** do not leave them empty; if unknown, add a short note under that heading explaining why.
- **Banned:** never list any path whose **basename** is `readme.md` in **any** casing (`README.md`, `readme.md`, etc.) in the Evidence index. **Never** list paths under **`.opencode/`** either (tooling copy, not product source).

### Revision log (mandatory)

- **`## Revision`** sits **immediately before** **`## Evidence index`**. **Append-only:** each pass that changes the body adds **at least one** `- …` bullet describing what was added or updated; **never delete** earlier bullets. **First write:** include an initial bullet (e.g. **Initial draft**).

## Output template

Write **exactly** the content for **`{{OUTPUT_FILE_ABSOLUTE}}`** using this skeleton. Replace prose; keep headings unless PLAN overrides. **R21:** every substantive statement in the body sections must appear again in **Evidence index** with `path:line` or `path:start-end`, or as *(inference)* with the strongest supporting cite (`{{CITATION_FORMAT_EXAMPLE}}`).

```markdown
# Application architecture

**Repository root (analysis):** {{WORKTREE_ROOT}}

## Summary

<!-- One short paragraph; cite high-level entry points. -->

## What kind of UI this is

<!--
  When applicable only: table (Platform, Framework, Visual style, Architecture, Data binding, etc.).
  Note non-UI pieces (services, data-module .dfm, tray/minimize behaviour) vs operator screens.
  Omit this section or one honest line if there is no UI. Evidence index must support each row.
-->

## Architecture diagrams (Mermaid)

<!--
  MANDATORY: at least one fenced code block with language "mermaid" below this heading.
  First line inside each fence: %%{init: {'theme':'neutral'}}%% (see MERMAID.md — Mermaid 11.13, neutral theme).
  Recommended coverage (use what fits the repo — add more blocks in this section or under other ## headings as needed):
  - System / context: major actors, external systems, this app boundary (flowchart or graph).
  - Components: internal subsystems and dependencies (graph or flowchart).
  - Data or control flow: sequenceDiagram or flowchart for a representative request, job, or event path.
  Each diagram: short title (### or bold line), then the fence, then optional one-line caption.
  Add extra diagrams when they clarify; avoid redundant copies of the same structure.
-->

### <!-- e.g. System context -->

<!-- Open fence with language tag mermaid; first line %%{init: {'theme':'neutral'}}%% then diagram body; close fence. -->

### <!-- Optional: further diagrams — e.g. Internal components, Request sequence, Deployment -->

## Context and boundaries

<!-- Runtime, deployment units, external systems; cite configs and docs. You may add another Mermaid block here if it fits better than the main diagrams section. -->

## Major components

<!-- Subsystems, apps, packages; cite module layout. -->

## Data flow

<!-- Request/response, events, persistence; cite pipelines. A sequenceDiagram or flowchart here is encouraged when non-trivial. -->

## Cross-cutting concerns

<!-- Auth, logging, i18n, etc.; cite shared modules. -->

## Risks and gaps

<!-- Explicit unknowns; still cite whatever partial evidence exists or mark inference. -->

## Revision

<!--
  Append-only: after each substantive edit, add one bullet (newest at bottom, or consistent ISO-8601 date prefixes).
-->

- <!-- e.g. Initial draft: diagrams and narrative from src/ and configs. -->

## Evidence index

- <!-- claim → `src/...:42` -->
- <!-- diagram edge "A→B" grounded → `src/...:10-18` -->
- <!-- *(inference)* … → `src/...:10-18` -->
```

## Evidence (**R21**)

Follow **Non-empty chapters and Evidence index** above. Every substantive claim must cite **`path:line`** or **`path:start-end`** per **`{{CITATION_FORMAT_EXAMPLE}}`**. Label inference explicitly. **Architecture diagrams:** tie major nodes and relationships to **Evidence index** entries (same file may support multiple diagram elements).

## Harness wiring

§3.5.1. Exactly **one** output file at **`{{OUTPUT_FILE_ABSOLUTE}}`**. Do not write coordination list JSON or `index-application-context.json`.
