Skip to content

architecture.rst: add aw-server-rust, misc. cleanup #160

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

architecture.rst: add aw-server-rust, misc. cleanup #160

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9e1b854
`architecture.rst`, add `aw-server-rust`, misc. cleanup
mrienstra Oct 31, 2025
00baacc
`custom.css`: make inline <code> look less alarming
mrienstra Oct 31, 2025
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
4 changes: 4 additions & 0 deletions src/_static/css/custom.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,10 @@ code {
color: rgb(51, 51, 51);
}

.rst-content code.literal, .rst-content tt.literal {
color: #a34400;
}

.rst-content .section ul p {
margin-bottom: 0px !important;
}
43 changes: 25 additions & 18 deletions src/architecture.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,57 +15,64 @@ The illustration below is a graph of the fundamental dependencies between projec
Server
------

Known as :gh-aw:`aw-server`, it handles storage and retrieval of all activities/entries in buckets. Usually there exists one bucket per watcher.
ActivityWatch has two server implementations:

The server also hosts the Web UI (aw-webui) which does all communication with the server using the REST API.
- :gh-aw:`aw-server` - The current default Python implementation
- :gh-aw:`aw-server-rust` - A Rust implementation that is the planned future default

Clients (watchers, importers, and observers)
--------------------------------------------
The server handles storage and retrieval of all activities/entries in buckets. Usually there exists one bucket per watcher.

Since aw-server doesn't do any data collection on it's own, we need watchers that observe the world and sent the data off to aw-server for storage.
The server also hosts the Web UI (``aw-webui``) which does all communication with the server using the REST API.

These utilize the aw-client library for making requests to the aw-server.
Clients (watchers and importers)
--------------------------------

Since ``aw-server`` doesn't do any data collection on it's own, we need watchers that observe the world and sent the data off to ``aw-server`` for storage.

These utilize the ``aw-client`` library for making requests to the ``aw-server``.

ActivityWatch can't track everything, so sometimes you might want to import data from another source, that's where importers come in.

For a list of watchers, see :doc:`watchers`. For a list of importers see :doc:`importers`.


User interfaces
---------------

ActivityWatch currently has two user interfaces, aw-qt and aw-webui.
ActivityWatch currently has two user interfaces, ``aw-qt`` and ``aw-webui``.

- :gh-aw:`aw-qt` - Manages the server and watchers to make ActivityWatch easy to use for end-users.
- :gh-aw:`aw-webui` - Offers visualization and an overview of the database. Hosted by aw-server in the bundle.
- :gh-aw:`aw-webui` - Offers visualization and an overview of the database. Hosted by ``aw-server`` in the bundle.

Libraries
---------

Some of the logic of ActivityWatch is shared across the server and clients, for these cases we moved some logic into separate libraries.

aw-core
^^^^^^^
:gh-aw:`aw-core`
^^^^^^^^^^^^^^^^

The aw-core library contains many of the essential parts of ActivityWatch, notably:
The ``aw-core`` library contains many of the essential parts of ActivityWatch, notably:

- The `buckets-and-events`
- The datastore layer
- Event transformation and queries
- Utilities (configuration, logging, decorators)

aw-client
^^^^^^^^^
:gh-aw:`aw-client`
^^^^^^^^^^^^^^^^^^

Writing these clients is something we've tried to make as easy as possible by creating client libraries with a clear API.
A client could both be a watcher which sends data as well as a visualizer which fetches and presents data from the aw-server.
A client could both be a watcher which sends data as well as a visualizer which fetches and presents data from the ``aw-server``.

Currently the primary client library is written in Python (known simply as aw-client) but a client library written in JavaScript is on the way and is expected to have the same level of support in the future.
Currently the primary client library is written in Python (known simply as ``aw-client``) but a client library written in JavaScript is on the way and is expected to have the same level of support in the future.

- :gh-aw:`aw-client` (Python)
- :gh-aw:`aw-client-js` (TypeScript/JavaScript, beta)
- :gh-aw:`aw-client-rust <aw-server-rust/tree/master/aw-client-rust>` (Rust, work in progress)

aw-analysis
^^^^^^^^^^^
:gh-aw:`aw-research`
^^^^^^^^^^^^^^^^^^^^

There are also plans to create a library called :gh-aw:`aw-analysis` to aid in
There are also plans to create a library called ``aw-research`` to aid in
different types of analysis and transformation one might want to make using ActivityWatch data.