Skip to content

Commit 39dfd80

Browse files
bougymanclaude
andauthored
CRY-56: docs(linear): add Ash domain ERD and AGENTS.md maintenance contract (#142)
## Summary - Creates `documents/ash-domain-erd.adoc` as the canonical, current inventory of the `LinearCli.Linear` Ash domain - Covers all 8 resources, 20 actions, 17 domain code interfaces, GraphQL/nested-data associations, and shared helpers - Adds a `## Domain documentation` section to `AGENTS.md` with an explicit same-change maintenance contract ## What the ERD document contains - **Architecture overview**: explains no local data layer — the Linear GraphQL API is the sole backing store; all actions are manual implementations calling `LinearCli.Api` directly - **Resource inventory table**: all 8 resources with primary key and public attributes - **Association table**: every source→target association with cardinality, attribute name, and implementation type (all labeled "GraphQL/nested-data" — zero Ash DSL relationships exist) - **ERD diagram** (Mermaid `erDiagram` block) with all associations labeled `[nested]` - **Action/interface matrix**: maps every domain code interface to its action, action type, manual module, and GraphQL operation (20 rows covering all 17 defined code interfaces plus any action-only entries) - **Shared helpers section**: `Issue.Update` (shared issueUpdate mutation runner for 4 update actions) and `Paginate` (cursor-based pagination used by 3 read actions) - **Maintenance contract** section (also mirrored into AGENTS.md) ## Test plan - [x] `mix compile --warnings-as-errors` passes (no Elixir changes) - [x] `mix test` — 12 tests, all pass (no code changes) - [x] Document is AsciiDoc under `documents/`, accurately reflects the code - [x] Every current resource, action, and code interface is represented - [x] All associations labeled by implementation type (GraphQL/nested-data vs Ash DSL) - [x] Diagram has a complete plain-text table equivalent - [x] `AGENTS.md` maintenance contract is specific and actionable - [x] `documents/project-structure.adoc` cross-link deferred (CRY-55 not yet merged) Closes https://linear.app/cryptokairos/issue/CRY-56/document-and-maintain-the-ash-domain-erd 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 33176bd commit 39dfd80

2 files changed

Lines changed: 452 additions & 0 deletions

File tree

AGENTS.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,15 @@ Update this section when adding a new top-level directory, a new major module
9393
or a new phase plan document. File-level changes inside existing directories do
9494
not need a structural-doc update.
9595

96+
## Domain documentation
97+
98+
- Ash domain ERD: documents/ash-domain-erd.adoc — canonical inventory of
99+
the `LinearCli.Linear` domain: resources, actions, code interfaces,
100+
GraphQL associations, and shared helpers. **Must be updated in the same
101+
change** whenever an Ash resource, action, code interface, association
102+
attribute, or shared helper is added, removed, renamed, or materially
103+
changed.
104+
96105
## Standards
97106

98107
- Conventional Commits: app/usage-rules.md — enforced by the `commit-msg`

0 commit comments

Comments
 (0)