Skip to content

Docs: README, glossary and ADRs in arocapi's terms #62

Closed

Description

@johnf

Parent

#52

What to build

Bring the docs in line with arocapi and with the behaviour from the other #52 tickets.

  • README: for operators and developers. Operators can deploy without reading arocapi's docs, and developers get deep links to them (arocapi.crate-works.org, linked as it is). Rewrite "How it fits together" in arocapi's terms, one sentence per part (storage backend content and metadata halves, search backend, visibility, access), each with a deep link. Fix the Licences section: metadata is covered as well as content, the enrolment link comes back on the entity's access rather than on the error, and anonymous requests get 401 while signed-in ones get 403. Describe the sandboxing and Caddy headers as they now are, give the right reason for the separate admin origin, and make clear "ADR 0002" is ldacapi's. Use pnpm import, the database index and entityType throughout, and note that a moved parent collection needs its children reindexed. Drop text that only restates arocapi's docs.
  • GLOSSARY.md: add Crate (one RO-Crate stored as one OCFL object, the unit of import, indexing and admin actions; avoid "OCFL object" and "collection"), Import (bringing RO-Crates into the OCFL repository: pnpm import today, the deposit API in future), Index (building the database index and search index from the repository; rebuildable), Database index (the Entity and File rows arocapi reads; arocapi's Rows) and Search index (the search documents in arocapi's search backend). Link to arocapi's glossary for Record, Metadata, Content and Row.
  • New ADR: each entity's metadata is a virtual crate built at index time (the entity as root plus what it links to, with Dataset, conformsTo and license added), only as fresh as the last index run. This is chosen over serving the crate's whole ro-crate-metadata.json.
  • CLAUDE.md: the arocapi upgrade note also says to recheck the README's links to arocapi's docs.

Ships on the one #52 branch and PR, as its own commit. See #52 for the decisions behind it.

Acceptance criteria

  • README describes the behaviour from the other Align with arocapi 5 and rewrite the README in its terms #52 tickets, with deep links to arocapi's docs where it mentions an arocapi concept
  • No README text contradicts arocapi 5's docs; "structural index" is gone
  • The Licences, sandboxing/Caddy and admin-origin sections are corrected as above
  • GLOSSARY.md has the five new terms and links to arocapi's glossary
  • The virtual-crate ADR exists and states the decision as it currently stands
  • CLAUDE.md's arocapi upgrade note includes rechecking the README's links

Metadata

Metadata

Assignees

No one assigned

    Labels

    ready-for-agentFully specified, ready for an AFK agent

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions