Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 12 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,25 +1,29 @@
<picture>
<source media="(prefers-color-scheme: dark)" srcset="./logo-dark.svg">
<img alt="Atomic Place" src="./logo.svg">
<img alt="atomic.place" src="./logo.svg">
</picture>

[![crates.io](https://img.shields.io/crates/v/atomic-server)](https://crates.io/crates/atomic-server)
[![Discord chat](https://img.shields.io/discord/723588174747533393.svg?logo=discord)](https://discord.gg/a72Rv2P)
[![MIT licensed](https://img.shields.io/github/license/atomicdata-dev/atomic-server.svg?color=blue&logo=github&logoColor=blue)](./LICENSE)
[![github](https://img.shields.io/github/stars/atomicdata-dev/atomic-server?style=social)](https://github.com/atomicdata-dev/atomic-server)

**Atomic Place is a local-first workspace for documents, tables, files, chat and apps.**
It works on your device and can sync through a self-hosted AtomicServer or optional
[managed services](https://atomic.place). The underlying [Atomic Data](https://docs.atomicdata.dev/atomic-data-overview)
specification is open.
**atomic.place is a local-first workspace for documents, tables, files, chat and apps.**
It works on your device and can sync through a self-hosted AtomicServer or the hosted service at
[atomic.place](https://atomic.place). The underlying [Atomic Data](https://docs.atomicdata.dev/atomic-data-overview)
specification is open. It comes in three propositions:

- **[Personal Data Store](https://docs.atomicdata.dev/personal-data-store)**: your identity is a key, your data is encrypted on your own devices, and every edit is signed by you.
- **[All-in-One Workspace](https://docs.atomicdata.dev/all-in-one-workspace)**: documents, tables, chat, meetings, canvas, websites, AI and apps, with one permission model.
- **[Local-first Sync Engine](https://docs.atomicdata.dev/sync-engine)**: build apps on the same Loro CRDT store and sync protocol, with no backend of your own.

This repo includes:

- **Atomic Place**, the workspace in the [browser](/browser/data-browser), on [desktop](/desktop)
- **atomic.place**, the workspace in the [browser](/browser/data-browser), on [desktop](/desktop)
and on mobile.
- **AtomicServer**, the [self-hostable server](/server) for storage, search, sharing and sync.
- [`docs`](docs/README.md) documentation / specification for Atomic Data ([docs.atomicdata.dev](https://docs.atomicdata.dev)).
- [Atomic Data Browser](/browser/data-browser/README.md), the React front-end for Atomic Place.
- [Atomic Data Browser](/browser/data-browser/README.md), the React front-end for atomic.place.
- [`@tomic/lib`](/browser/lib/README.md) JS NPM library.
- [`@tomic/react`](/browser/react/README.md) React NPM library.
- [`@tomic/svelte`](/browser/svelte/README.md) Svelte NPM library.
Expand All @@ -29,7 +33,7 @@ This repo includes:

_Status: alpha. [Breaking changes](CHANGELOG.md) are expected until 1.0._

## Atomic Place
## Features

<!-- We re-use this table in various places, such as README.md and in the docs repo. Consider this the source. -->
- 🏠 **Local-first**: works offline in the browser, syncs when you reconnect with [Atomic Sync](https://docs.atomicdata.dev/sync).
Expand Down
7 changes: 7 additions & 0 deletions docs/src/SUMMARY.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
## Table of contents

# Why Atomic

- [Why Atomic](why-atomic.md)
- [Personal Data Store](personal-data-store.md)
- [All-in-One Workspace](all-in-one-workspace.md)
- [Local-first Sync Engine](sync-engine.md)

# What is Atomic Data

- [Atomic Data Overview](atomic-data-overview.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/src/agents.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,5 +34,5 @@ When a client generates a keypair, the public key immediately determines the Age
See the [DID specification](did.md) for details on how agent DIDs work and are resolved.

One way to start using your Agent is by accepting an [Invite](invitations.md) with your public key.
The server will derive the `did:ad:agent:` identifier and grant the requested rights.
The server will derive the `atomic:agent:` identifier and grant the requested rights.
Alternatively, you can host an [Atomic Server](https://crates.io/crates/atomic-server) and use the `/setup` invite to configure the root Agent.
43 changes: 43 additions & 0 deletions docs/src/all-in-one-workspace.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
{{#title All-in-One Workspace: documents, tables, chat and apps in one place}}
# All-in-One Workspace

The web app on [atomic.place](https://atomic.place), the desktop and mobile apps and a self-hosted AtomicServer all serve the same workspace.
It replaces a stack of separate tools with one place where everything is linked, searchable and shared with the same permissions.

## What is in it

| Area | What you can do |
| --- | --- |
| **Documents** | Collaborative rich text with live cursors and full history. |
| **Tables** | A strict-schema table editor with keyboard navigation and copy / paste, plus Kanban, calendar, dashboard and timer views on any table. See [Tables](atomicserver/gui/tables.md). |
| **Templates** | Start from a ready-made setup such as an issue tracker, a CRM, project tasks, a time tracker, team handbook or lecture notes. |
| **Chat and meetings** | Group chat with attachments, search and replies, and video meetings with shared notes and presence. |
| **Canvas** | An infinite drawing surface, shared live. |
| **Files** | Upload, download and preview attachments, stored by content hash. See [Files](files.md). |
| **Websites** | Design pages in the browser, publish, and roll back to any earlier version. |
| **Forms** | Build forms on your own data models. |
| **Custom data models** | Your own Classes and Properties in the Ontology Editor, shared as [Atomic Schema](schema/intro.md). |
| **AI** | An assistant that can use [MCP](https://modelcontextprotocol.io/) servers as tools and works with any model through OpenRouter or a local Ollama. See [AI and Atomic Assistant](atomicserver/gui/ai-and-atomic-assistant.md). |
| **Apps and plugins** | Custom screens in plain JavaScript, and WebAssembly [plugins](plugins.md) that extend the server. |
| **Virtual drive** | Mount a Drive as a folder in Finder or Explorer (desktop app). |
| **Search** | Full-text search with typeahead and fuzzy matching, running on both server and client. |

## What makes it one workspace

- **One permission model.** The same read / write rights, [hierarchies](hierarchy.md) and [invite links](invitations.md) apply to a document, a table row, a chat channel and a website.
- **One data model.** A row in a table, a chat message and a page are all Resources, linked by URL. You can link and embed across areas without integration glue.
- **Real-time collaboration.** Live cursors, typing indicators, avatars and following a teammate work over the same [sync](sync.md) connection as the data itself.
- **Offline everywhere.** The whole workspace works without a connection, because the data is local.
- **Extensible.** Define your own Classes, add views, write apps, install plugins. Nothing in the workspace is special-cased: it is built on the same Classes, Properties and APIs you can use.

## Where to run it

- **Hosted:** open [atomic.place](https://atomic.place) in a browser, or install the desktop or mobile app.
- **Self-hosted:** one binary that holds the server, the web app, the database and search. See [installation](atomicserver/installation.md).
- **Both:** apps pair with a server of your choice and fall back to local-only. Moving between them does not change your identity or your data.

New to the interface? Read [Using the GUI](atomicserver/gui.md).

## Status

Atomic is alpha software and breaking changes are expected until 1.0. See the [roadmap](roadmap.md).
4 changes: 2 additions & 2 deletions docs/src/astro-guide/6-generating-types.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,15 @@ A config file called `atomic.config.json` has been generated, it should look som
```

Now let's add the subject of our ontology to the `ontologies` list.
To get the subject, open the ontology in the Atomic Data browser and copy the `did:ad:…` identifier from the search bar at the bottom (or from `?subject=` in the address bar) — not the `https://…/did:ad:…` URL.
To get the subject, open the ontology in the Atomic Data browser and copy the `atomic:…` identifier from the search bar at the bottom (or from `?subject=` in the address bar) — not the `https://…/atomic:…` URL.
Set `serverUrl` to the origin of your Atomic Server.

```json
{
"outputFolder": "./src/ontologies",
"moduleAlias": "@tomic/lib",
"serverUrl": "http://localhost:9883",
"ontologies": ["did:ad:<your-ontology-id>"]
"ontologies": ["atomic:<your-ontology-id>"]
}
```

Expand Down
10 changes: 6 additions & 4 deletions docs/src/atomic-data-overview.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
{{#title Atomic Data}}
![# Atomic Data Docs - Overview](assets/atomic_data_logo_stroke.svg)

Atomic is a [personal data store, an all-in-one workspace and a local-first sync engine](why-atomic.md), built on an open specification.

**Atomic Data is a modular specification for sharing, modifying and modeling graph data. It combines the ease of use of JSON, the connectivity of RDF (linked data) and the reliability of type-safety.**

![Venn diagram showing Atomic Data is the combination of JSON, RDF and Type-Safety](assets/venn.svg)
Expand Down Expand Up @@ -30,7 +32,7 @@ It is type-safe (you know if something is a `string`, `number`, `date`, `URL`, e
The default serialization format for Atomic Data is [JSON-AD](core/json-ad.md), which is simply JSON where each key is a URL of an Atomic Property.
These Properties are responsible for setting the `datatype` (to ensure type-safety) and setting `shortnames` (which help to keep names short, for example in JSON serialization) and `descriptions` (which provide semantic explanations of what a property should be used for).

Every Resource, Property and Class is named by a URL. Which URL shapes exist, from `https://` vocabularies to location-independent `did:ad:` identifiers, is explained in [URLs and identifiers](urls.md); read that first if you are new here.
Every Resource, Property and Class is named by a URL. Which URL shapes exist, from `https://` vocabularies to location-independent `atomic:` identifiers, is explained in [URLs and identifiers](urls.md); read that first if you are new here.

[Read more about Atomic Data Core](core/concepts.md)

Expand All @@ -42,9 +44,9 @@ Atomic Data Extended is a set of extra modules (on top of Atomic Data Core) that

## Tools & libraries

- [Atomic Cloud](https://atomicserver.eu) is the place to start: the web app, an always-on device for your data, and the app downloads, all in one place
- The **web app**: documents, tables, chat, files and an ontology editor, working offline in the browser ([demo on atomicdata.dev](https://atomicdata.dev))
- The **desktop and mobile apps** (macOS, Windows, Linux, Android and iOS), built with Tauri: the same app with a full node inside, so it can be paired with directly and act as an always-on device. Download them from [atomicserver.eu](https://atomicserver.eu) or the [GitHub releases](https://github.com/atomicdata-dev/atomic-server/releases)
- [atomic.place](https://atomic.place) is the place to start: the hosted web app, plus the app downloads
- The **web app**: documents, tables, chat, files and an ontology editor, working offline in the browser
- The **desktop and mobile apps**, built with Tauri: the same app with a full node inside, so it can be paired with directly and act as an always-on device. Download them from [atomic.place](https://atomic.place) or the [GitHub releases](https://github.com/ontola/atomic-server/releases)
- Build a web app with [@tomic/lib](js.md), [@tomic/react](usecases/react.md) or [@tomic/svelte](svelte.md), or a native app with [Flutter / Dart](flutter.md), on top of the same Rust core
- Prefer to run your own always-on device? [Self-host atomic-server](atomicserver/installation.md), a single binary
- The command line tool [atomic-cli](rust-cli.md) and the Rust library [atomic_lib](rust-lib.md)
Expand Down
6 changes: 4 additions & 2 deletions docs/src/atomic-server.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
{{#title AtomicServer: the always-on device for your Atomic Data}}
# AtomicServer

[`AtomicServer`](https://github.com/atomicdata-dev/atomic-server) is the _reference implementation_ of the Atomic Data Core + Extended specification: a single binary that is a graph database, a real-time headless CMS and a web app.
[`AtomicServer`](https://github.com/ontola/atomic-server) is the _reference implementation_ of the Atomic Data Core + Extended specification: a single binary that is a graph database, a real-time headless CMS and a web app.
It was developed parallel to this specification, and it served as a testing ground for various ideas (some of which didn't work, and some of which ended up in the spec).

AtomicServer is how you self-host the three things described in [Why Atomic](why-atomic.md): a [Personal Data Store](personal-data-store.md) that is always reachable, the [All-in-One Workspace](all-in-one-workspace.md) served as a web app, and the always-on peer of the [Local-first Sync Engine](sync-engine.md).

## The always-on device

In a [local-first](local-first.md) system every device holds its own copy of the data and does its own signing.
Expand All @@ -15,7 +17,7 @@ That is AtomicServer's job: it is the device that never sleeps.
- It holds a **backup** that survives a lost phone, without holding your key: every commit it stores is signed by the Agent that made it, so the server can replicate but never author.
- It serves the same data over **HTTP**, for `curl`, static site generators and search engines, next to the sync connection the apps use.

You can run one on a laptop, a Raspberry Pi, a VPS or a home NAS. [Atomic Cloud](https://atomicserver.eu) runs one for you.
You can run one on a laptop, a Raspberry Pi, a VPS or a home NAS. [atomic.place](https://atomic.place) can run one for you.
The same `atomic_lib` also runs inside the browser and in [Flutter apps](flutter.md), which is why a phone can act as an always-on device for another phone, but a server is the shape most people want for the role.

If you are here to build an app, the [local-first guide](local-first-guide/1-index.md) starts without a server and adds one in step 4; the rest of this chapter is about running and using the server itself.
Expand Down
8 changes: 4 additions & 4 deletions docs/src/atomicserver/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,17 +29,17 @@ Typically, you pass query parameters to these endpoints to specify what you want

<!-- We have a subset of the [API documented using Swagger / OpenAPI](https://editor.swagger.io/?url=https://raw.githubusercontent.com/atomicdata-dev/atomic-server/master/server/openapi.yml). -->

## Fetching `did:ad:` resources over HTTP
## Fetching `atomic:` resources over HTTP

Most resources created since the move to [local-first](../local-first.md) are named by a [`did:ad:` identifier](../urls.md) rather than by an HTTP URL.
Most resources created since the move to [local-first](../local-first.md) are named by a [`atomic:` identifier](../urls.md) rather than by an HTTP URL.
An AtomicServer that holds such a resource serves it at a `/did` endpoint, and also accepts the identifier as a path:

```sh
curl -H "Accept: application/ad+json" "https://atomicdata.dev/did?subject=did%3Aad%3A{genesis}"
curl -H "Accept: application/ad+json" "https://atomicdata.dev/did:ad:{genesis}"
curl -H "Accept: application/ad+json" "https://atomicdata.dev/atomic:{genesis}"
```

The response's `@id` is the DID, and a `Link: <did:ad:…>; rel="canonical"` header names it too, so a client that arrived through this server's address can remember the location-independent identity.
The response's `@id` is the DID, and a `Link: <atomic:…>; rel="canonical"` header names it too, so a client that arrived through this server's address can remember the location-independent identity.
Writes never go through a resource URL: they are signed commits, sent over the [sync](../sync.md) connection or to `/commit`.

## Libraries or API?
Expand Down
2 changes: 1 addition & 1 deletion docs/src/atomicserver/faq.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## I can't find my question, I need support

- Create an [issue on github](https://github.com/atomicdata-dev/atomic-server/issues) or [join the discord](https://discord.gg/a72Rv2P)!
- Create an [issue on github](https://github.com/ontola/atomic-server/issues) or [join the discord](https://discord.gg/a72Rv2P)!

## Do I need NGINX or something?

Expand Down
2 changes: 1 addition & 1 deletion docs/src/atomicserver/gui.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ At the start these will be:
## Creating an agent
To create data in AtomicServer you'll need an agent.
An agent is like a user account, it signs the changes (commits) you make to data so that others can verify that you made them.
Agents are identified by a DID derived from their public key (`did:ad:{publicKey}`), so they can be used on any AtomicServer without needing to be registered first.
Agents are identified by an identifier derived from their public key (`atomic:{publicKey}`), so they can be used on any AtomicServer without needing to be registered first.

To get started, you can use the [demo invite](https://atomicdata.dev/invites/1) on atomicdata.dev, or the `/setup` invite on your own server.

Expand Down
Loading