first commit

docs/modeling-conventions.md

@@ -0,0 +1,48 @@
+# LikeC4 modeling conventions
+
+These conventions keep a model readable and consistent as it grows.
+
+## Relationship direction
+
+Arrows point from the initiating element to the receiving element:
+
+> initiator -> receiver
+
+A normal response to a request is implicit. Model a reverse relationship only when it represents an independent architectural interaction.
+
+Use the most specific useful endpoints. Prefer a parent element when implementation detail would make the view harder to read.
+
+## Relationship labels
+
+- Give every relationship a concise, active, present-tense label.
+- Prefer precise verbs over the generic `uses`.
+- Describe one architectural responsibility per relationship.
+- Put protocols and communication technologies in the relationship's `technology` property rather than its title.
+
+## Relationship kinds
+
+Use the smallest applicable relationship kind from `src/specification.c4`:
+
+| Kind | Meaning |
+| --- | --- |
+| `sends` | Transfers a request or message to another service. |
+
+The relationship title describes the specific interaction; the kind provides consistent classification.
+
+```likec4
+intakeDesk .sends routingDesk 'forwards sorting requests'
+```
+
+Do not introduce a relationship kind for a single exceptional interaction. Add one only when it captures a recurring architectural distinction, and update this table in the same change.
+
+## Static and dynamic views
+
+Static views show enduring dependencies and interactions. Use dynamic views when sequence, timing, callbacks, or a multi-step scenario is the subject of the diagram.
+
+## Visual styling
+
+Relationship semantics come from direction, kind, and label, not color alone. Keep styling simple unless a visual distinction materially improves a view.
+
+## Validation
+
+Run `npm run validate` after every model change. LikeC4 validation checks model correctness, but these project-specific naming and labeling conventions still require review.