# `docs/architecture/`

How LOMA-PORTAL is built. Diagrams rendered in mermaid; readable on GitHub, GitLab, Obsidian, VS Code preview.

| File                                           | Scope                                                             |
| ---------------------------------------------- | ----------------------------------------------------------------- |
| [`overview.md`](overview.md)                   | C4 — system context + containers + per-component (.NET + worker)  |
| [`request-lifecycle.md`](request-lifecycle.md) | Sequence diagrams: login, dashboard, refresh, audit, notification |

## Short form

For a 1-page summary the AI agent loads on demand: [`.claude/context/architecture-summary.md`](../../.claude/context/architecture-summary.md).

## Machine-readable form

For `dependency-cruiser` + repo intelligence: [`tools/validators/module-boundaries.json`](../../tools/validators/module-boundaries.json) + [`tools/validators/dependency-map.json`](../../tools/validators/dependency-map.json).

## Adding new diagrams

Use mermaid (no PNG / draw.io files). Diagrams that drift from code are worse than no diagrams — keep these in sync when:

- New top-level container is added (e.g. a search service).
- A new external dependency is introduced.
- Direction-of-deps changes (write an ADR too).
