Stefan
882e97509a
- Updated FdsSqlOptions to accept an optional ILogger parameter for improved error logging. - Modified FdsMfr and FdsMfrClient classes to pass the logger instance to FdsSqlOptions. - Added detailed error logging in various methods to capture SQL execution issues and file handling errors. - Improved documentation for FdsSqlOptions to clarify logging behavior. - Updated Archive class to log compression errors, enhancing traceability of failures. - Adjusted project configuration to suppress specific warnings related to transitive dependencies. - Added NuGet.config to define package sources for dependency management. - Updated submodule references for OCORE and related projects.
67 lines
2.1 KiB
Markdown
67 lines
2.1 KiB
Markdown
# 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).
|