# Concepts

This folder holds **living design write-ups** of how a subsystem currently
works: its moving parts, data flow, and how they fit together. Unlike
[`../Decisions`](../Decisions/README.md), concept docs are **not** immutable
— keep them in sync with the implementation as it evolves.

## What belongs here

"How does the notification pipeline work end to end" is a concept doc. "Why
did we choose SignalR over polling for it" is a decision. A single feature
area typically has one concept doc and may reference several decisions that
shaped it.

## File naming

`kebab-case-topic.md` (no numbering — concepts aren't sequential events).

## Required YAML frontmatter

```yaml
---
status: Active            # Active | Deprecated
lastUpdated: 2026-07-03
applyTo:                  # glob(s) — files/areas this concept describes
  - "Fuchs/Notifications/**"
relatedDecisions:         # filenames in ../Decisions this concept implements
  - "0001-domain-events-and-notification-triggers.md"
---
```

**Agents must scan the YAML frontmatter of every file in this folder first**
and only read the full body of concepts whose `applyTo` glob matches the
files they're about to touch, or whose subject is otherwise clearly relevant.

## Body template

```markdown
# Topic

## Summary
One paragraph: what this subsystem does and why it exists.

## How it works
The mechanics — components, data flow, sequencing. Diagrams (ASCII/mermaid)
welcome where they clarify.

## Key files
Bullet list of the primary files/classes involved.

## Related decisions
Links to the ADRs in `../Decisions` that shaped this design.
```

## Rules

- **Keep concepts current.** When you materially change how a documented
  subsystem works, update its concept doc in the same change — don't let it
  drift from the code.
- **Create a concept doc for new non-trivial subsystems.** If you build
  something a future agent would need a paragraph of context to safely
  modify, write that paragraph here instead of making them re-derive it from
  the diff.
- Concepts describe **current** behavior. If something changes, edit the
  doc in place — don't append a changelog inside it (git history is the
  changelog).