portal/docs/architecture/README.md

# docs/architecture — system diagrams and models

C4 and architecture diagrams for Лидерра, written as Mermaid source. Generated
and maintained with the `mermaid` skill (`.claude/skills/mermaid/`).

## Boundaries

- **`docs/architecture/`** (here) — *visual* models: C4 diagrams, system
  context, container and component views. Not normative.
- **`docs/adr/`** — Architecture Decision Records: the *decisions* and their
  rationale. An ADR may reference a diagram here.
- **`docs/Открытые_вопросы_v8_3.md`** — *open* product/business/legal questions.

See [ADR-000](../adr/ADR-000-adr-process.md) for the full boundary rule.

## Diagrams

| File | View | Mermaid type |
|---|---|---|
| [c4-context.md](c4-context.md) | System Context — Лидерра and its actors / external systems | `C4Context` |
| [c4-component-layers.md](c4-component-layers.md) | Component — backend layer dependency graph (deptrac-generated, drift-proof) | `flowchart` |

## Regenerating

Mermaid blocks render natively on GitHub. To author or revise a diagram, invoke
the `mermaid` skill and describe the view; it reads the matching syntax
reference (`.claude/skills/mermaid/references/`) and emits a ` ```mermaid `
block. No local renderer (`mmdc`) is required.

For pattern guidance when shaping a new subsystem, the `architecture-patterns`
skill covers Clean / Hexagonal / layered architecture and Domain-Driven Design.

The component-layer diagram ([c4-component-layers.md](c4-component-layers.md)) is
**not** hand-authored — deptrac generates it from code
(`cd app && php vendor/bin/deptrac analyse --formatter=mermaidjs`), so it cannot
drift. Regenerate it after any change to the layer model in `app/deptrac.yaml`.