Skip to content

docs: add ARCHITECTURE.md (#21) - #48

Open
malaysiaonelove wants to merge 1 commit into
Kqirox:mainfrom
malaysiaonelove:docs/architecture-md
Open

docs: add ARCHITECTURE.md (#21)#48
malaysiaonelove wants to merge 1 commit into
Kqirox:mainfrom
malaysiaonelove:docs/architecture-md

Conversation

@malaysiaonelove

Copy link
Copy Markdown

Summary

Adds ARCHITECTURE.md — the canonical architecture reference for the Orivex Contracts repository, as specified in issue #21.

Closes #21

What's included

  • Section 1 — System Overview: Mermaid diagram of all 6 contracts, callers, and USDC SAC token
  • Section 2 — Contract Roles: address aliases and one-line responsibilities
  • Section 3 — Cross-Contract Call Graph: sequence diagram + call table with source file line links
  • Section 4 — Trust Boundaries: principal hierarchy, 7 trust invariants, what each contract does NOT trust, recovery flows
  • Section 5 — Per-Contract Deep-Dives: storage layout tables, auth model, events, key constants for all 6 contracts
  • Section 6 — Wiring Guide: ordered deployment + initialization steps with exact stellar contract invoke commands and a Mermaid dependency flowchart
  • Section 7 — Panic Catalog: every panic message, its trigger condition, and source function for all 6 contracts
  • Section 8 — Extension Guide: adding a new contract, event, admin role, storage key; generating API docs via cargo doc

Also adds .markdownlint.json to configure lint rules repo-wide (disables MD013 line-length, scopes MD024 to siblings-only).

Acceptance criteria checklist

  • Document is lint-clean (markdownlint-cli2: 0 issues)
  • Renders correctly on GitHub (Mermaid 10.x, standard GFM tables)
  • Cross-references source files for every claim (line-linked in call table and per-contract sections)

…, and extension guide

Closes Kqirox#21

- System overview Mermaid diagram covering all 6 contracts
- Cross-contract call graph (sequence diagram + call table with source links)
- Trust boundary analysis: principal hierarchy, invariants, recovery flows
- Per-contract deep-dives: storage layout, auth model, events, constants
- Step-by-step wiring/deployment guide with stellar CLI commands
- Full panic catalog for all 6 contracts
- Extension guide: new contracts, events, admin roles, storage keys
- .markdownlint.json to configure lint rules for the repo
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.

[21] Add ARCHITECTURE.md describing cross-contract flows, trust boundaries, and extension points

1 participant