System Design Specification
A technical design format for architecture boundaries, data contracts, failure handling, deployment and operational acceptance.
Overview and boundaries
Specify behaviours, not simply product names
Aster Sync is a fictional local-first event service for applications that must record events while disconnected and reconcile them when network access returns.
Write accepted events locally even when the network is unavailable.
Server reconciliation is authoritative; clients observe an explicit status.
Re-sent events never produce repeated business actions.
No claim of total ordering across devices.
Quality attributes and constraints
Show non-functional requirements alongside behaviour
| ID | Requirement | Verification method |
|---|---|---|
| NFR-01 | Local event acceptance does not depend on an internet connection. | Disconnect test while creating events. |
| NFR-02 | Each event has a globally unique identifier and a schema version. | Schema validation and duplicate replay test. |
| NFR-03 | Every server acknowledgement is durable before the client marks an event synchronized. | Crash and restart test. |
| NFR-04 | A replay with the same event identifier cannot apply a business action twice. | Idempotency integration test. |
| NFR-05 | Conflicts and invalid messages are visible to operators. | Quarantine and alert drill. |
Logical architecture
Four components; ownership explicitly separated
Capture and retransmit
- Assign event IDs before local commit.
- Persist requests before showing success.
- Retry with exponential backoff.
- Show queued, accepted and rejected states.
Validate and reconcile
- Authenticate sender and verify schema.
- Deduplicate using event ID.
- Evaluate version and business constraints.
- Publish a traceable final outcome.
Message and API contract
Example wire format and processing states
{
"eventId": "024f39c8-1b78-4e18-85f6-3ca054d8ab9b",
"aggregateId": "asset-204",
"deviceId": "device-07",
"sequence": 42,
"schemaVersion": 1,
"occurredAt": "2026-10-14T07:00:00Z",
"type": "InspectionCompleted",
"payload": { "result": "Pass", "evidenceCount": 2 }
}| API | Expected behaviour |
|---|---|
POST /v1/events | Durably accept, reject with a reason, or report already accepted. |
GET /v1/events/{id} | Return current ingestion and application state. |
GET /v1/sync?cursor= | Return scoped incremental changes with a durable cursor. |
Failure modes and recovery
Design for the scenarios users actually experience
| Scenario | Expected system response | Evidence |
|---|---|---|
| Client restarts mid-upload | Persisted event remains queued or accepted; safe retry on restart. | Restart test / dedup log |
| Server accepts but reply is lost | Client retries; same event ID returns existing outcome. | Network fault test |
| Conflicting updates | Conflict is explicitly rejected or queued for resolution. | Conflict report |
| Schema version unsupported | Reject safely with a machine-readable error; preserve event locally. | Contract test |
| Device clock incorrect | Server records receipt time separately; policies define handling. | Clock skew test |
Operations, security and rollout
Make ownership and testability part of the design
Measure oldest pending event, retry count and reconciliation latency.
Per-device credentials, revocation, encryption and audit context.
Rebuild one node, replay retained events and compare expected outcomes.
Document control
Example technical design record
| Field | Value |
|---|---|
| Author | Carlo Hennsa |
| Document type | System design (illustrative) |
| Reference | EX-SD-002 |
| Version | 1.0 |
| Issued | 14 October 2026 |
| Decision status | Proposed; requires engineering review |
| Scope | Fictional local-first synchronization service |