Quickstart
Open Atlas, save a record on the device, announce it to peers, and read it back, in about 20 lines.
In this quickstart you save a record on the device, announce it to other peers, and resolve it on the receiving side. Each step names its outcome so you know what to expect before you run it.
Before you start
You need three things from your application:
| Input | What it is |
|---|---|
| Identity | The principal your app acts as, with its DID and public key. |
| Storage path | A database location the app owns on the device. |
| Schema | The name, version, and digest of the data your records carry. |
Open Atlas
Open local identity and storage. The session is ready as soon as local storage is ready. Network readiness is observed separately, so the app works with no connection.
platform = Platform.open(identity, storage, application_protocols)
Outcome: a ready session. Possible errors are InvalidArgument and StorageFailure.
Save a record
Save application data under a replication scope. The call returns when the write is durable on this device. Replication to other peers continues in the background.
saved = platform.records.save(record, scope)
Outcome: a SaveResult with a stable entity_ref and a confirmed local commit. A local commit does not mean any other peer has the record yet.
Announce it
Publish a small notification that the record exists. The notification carries the entity_ref, not the data.
notice = platform.events.publish(event, publish_options)
Outcome: local acceptance of the event. Delivery to each peer is reported separately.
Listen on another peer
On the receiving peer, open a bounded receiver and wait for the next notification.
events = platform.events.subscribe(event_filter, subscription_options)
notice = await events.next()
Outcome: the next verified, fresh notification. Old and duplicate notifications are dropped for you.
Resolve the record
Fetch the data behind the notification. The state can arrive after the notification, so give the call a deadline.
record = await platform.records.resolve(notice.entity_ref, resolve_options)
Outcome: the latest authorized state available within the deadline. PendingState means the data has not arrived yet, not that it is missing.
Watch it sync and shut down
Observe replication progress for the scope, and stop the session when you are done.
progress = platform.sync.observe(scope)
await platform.shutdown()
Outcome: progress for the scope, then released resources. A committed write survives shutdown.
What you just relied on
Local first
Saves finish on the device. Replication follows independently.
Events and state are separate
A notification arrives first. The data is resolved on its own schedule.
Authority is explicit
Every save, publish and subscribe checks a signed capability.
Offline is normal
Reconnect behavior and the error model.
Next steps
- Model your data with schemas and records and documents.
- Add live data with streams.
- Learn the vocabulary in the glossary.
- Building a full application? Start with the Mission SDK.