docs: Architecture page + ADRs (the design reasoning)#17
Conversation
Senior docs explain how; this adds the *why* — the layer that makes the design judgment legible. - concepts/architecture.md: the four load-bearing choices (event-log not registry, one-DataNode graph, agents-first/tool-shaped, framework-agnostic pluggable core), each with the alternative rejected and the cost accepted on purpose — plus an explicit "what model-ledger is NOT" section. - adr/: five Architecture Decision Records (event-log, DataNode, agents-first, framework-agnostic profiles, storage-agnostic backends) with context, decision, consequences (+/-), and alternatives considered. - nav: Architecture under Concepts; Design decisions (the ADRs) under Reference. OSS-safe: generic reasoning only, no org-specific references. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 583462d124
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Storage, discovery, introspection, and compliance are all `@runtime_checkable` Protocols | ||
| discovered via entry points. Regulations live in **profiles** — a plugin layer — not in |
There was a problem hiding this comment.
In the extension scenario described here, a third party would publish a storage/discovery/compliance entry point and expect model-ledger to load it, but the repo has no loader for those groups: pyproject.toml only declares model_ledger.introspectors, validation uses the in-process register_profile decorator plus explicit built-in imports in src/model_ledger/validate/engine.py, and backends are only passed directly to Ledger(...) or via the fixed constructors in src/model_ledger/sdk/ledger.py. This makes the new architecture/ADR guidance misleading for plugin authors because their registered backend/profile/connector will never be discovered at runtime.
Useful? React with 👍 / 👎.
1 participant
Adds the why layer — what makes a repo read as deliberately designed rather than merely built.
OSS-safe (generic reasoning, no org-specific refs). Strict build clean; doctest passes.
🤖 Generated with Claude Code