Eight documents. One source of truth.
Suncly's architecture is written down before its code. The documents below describe the system component by component, entity by entity, and step by step. They are in the repository today and will be published here with early access. Where a document and the schema disagree, the schema wins.
Status: pre-prototype. The repository holds the architecture documentation and a package skeleton. No stage has started.
- SCHEMA.md
Architecture schema
System layout, components, data model, main flow, default approval policy, interfaces, stack, the non-negotiable rules, build order, and what is out of scope. The source of truth.
- docs/ARCHITECTURE.md
Architecture
Each component's responsibility, inputs, outputs, what it must never do, and how it fails safely. Also the A2A protocol facts Suncly depends on, checked against specification v1.0.1.
- docs/DATA_MODEL.md
Data model
The seven entities: agent, card_version, contract, test_case, attestation, run, decision. Fields, types, keys, relationships, enums, invariants, and an ER diagram.
- docs/FLOW.md
Attestation flow
One attestation from trigger to result, the attestation status lifecycle, and the failure paths: agent unreachable, budget exceeded, inconclusive verdicts, card changed mid-run.
- docs/API.md
Interfaces
The CLI command and the four HTTP endpoints, with example requests and responses.
- docs/POLICY.md
Approval policy
Risk levels, decision outcomes, when a human is required, the decision table, and how inconclusive results count.
- docs/DECISIONS.md
Decision records
The seven non-negotiable rules, each with its decision, reason and consequences.
- docs/ROADMAP.md
Roadmap
The six build stages, each with a definition of done, and what is not on the roadmap.
How the documents are written
- Where a document and the schema disagree, the schema wins.
- Behaviour the schema does not define is marked Proposed and tracked as an open question. No document decides silently.
- Protocol details still to be checked against the A2A specification are marked for verification.
- Numeric thresholds are deliberately absent. They are configured per customer and per risk level.