Skip to content

docs: architecture + glossary + error catalog#2

Merged
sirambrosio merged 3 commits into
mainfrom
docs/specs-polish
Apr 20, 2026
Merged

docs: architecture + glossary + error catalog#2
sirambrosio merged 3 commits into
mainfrom
docs/specs-polish

Conversation

@sirambrosio
Copy link
Copy Markdown
Contributor

Summary

Adds three high-leverage DX docs under `docs/`:

  • `ARCHITECTURE.md` — end-to-end system diagram (User → Frontend/CLI/MCP → SDK → Registry API → Contracts → Arweave) plus sequence diagrams for create BEO, grant consent, submit BioRecord, and destroy BEO. Documents component responsibilities and trust boundaries.
  • `GLOSSARY.md` — canonical normative definitions for BEO, IEO, BioRecord, ConsentToken, Scope, Intent, Domain, Guardian, Recovery, Relayer, plus taxonomy terminology.
  • `ERROR_CODES.md` — consolidated error catalog with stable codes cross-linked to contracts, API, SDK, CLI, and MCP sources. Identity / Consent / Crypto / BioRecord / Relayer / Configuration error families.

All three are cross-linked to each other and to the existing `spec/` + `docs/implementation-guide.md`.

Test plan

  • Render Mermaid diagrams on GitHub (verify all 5 diagrams display correctly)
  • Verify relative links resolve between `docs/` files
  • Cross-check error codes against actual implementations in `bsp-contracts`, `bsp-registry-api`, `bsp-sdk-typescript`, `bsp-cli`, `bsp-mcp`
  • Confirm canonical glossary terms match current spec files under `spec/`

🤖 Generated with Claude Code

sirambrosio and others added 3 commits April 20, 2026 10:08
- docs/ARCHITECTURE.md: system diagram + sequence diagrams for create BEO,
  grant ConsentToken, submit BioRecord, and destroy BEO flows. Component
  responsibilities + trust boundaries documented.
- docs/GLOSSARY.md: canonical definitions for BEO, IEO, BioRecord,
  ConsentToken, Scope, Intent, Domain, Guardian, Recovery, Relayer, and
  taxonomy terms. Normative — all implementations MUST use these meanings.
- docs/ERROR_CODES.md: consolidated stable error code catalog cross-linked
  to contracts, API, SDK, CLI, and MCP sources.
@sirambrosio sirambrosio merged commit 7f87444 into main Apr 20, 2026
1 check failed
@sirambrosio sirambrosio deleted the docs/specs-polish branch April 20, 2026 14:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant