Skip to main content

Explanation

Why RECAP is designed the way it is.

These pages cover why RECAP behaves as it does. Read them when a design decision seems surprising and you want the reasoning, or before committing to an approach that would be expensive to change.

They are not instructions. For steps, see the How-To Guides; for exact signatures, see the API Reference.

In reading order

  1. How RECAP Organizes Data — namespaces, the definition/record split, resource hierarchies, and the provenance graph. Start here.
  2. Query Model and Loading — why queries are immutable, why relationships are unloaded by default, and how the identity map keeps one entity as one object.
  3. Resource Loading — how resource trees are hydrated without issuing one query per child.
  4. Authentication and Authorization — actors, scopes, namespace grants, and why visibility is applied before filtering.
  5. Audit and Error Semantics — what is recorded about every mutation, and what is deliberately excluded.
  6. REST Query and Command Architecture — how remote clients reach the same behaviour as local ones over HTTP.

If you are new to RECAP, read Core Concepts first. It covers the same model in far less depth and makes these pages much easier to follow.