# Archipelago OS architecture

For a visual overview, open the [styled HTML architecture guide](architecture.html).

This is the source-level map for a node on current `main` (reviewed 2026-11-12).
It describes boundaries and ownership, not the acceptance status of a release
or a particular installed node. For those, use [Release & Testing](../Release%20%26%20Testing/README.md), the signed release records, and the exact node evidence.

## One node

```text
Browser / Companion
        |
        v
Nginx: web UI, authenticated RPC and app routes
        |
        v
Rust backend: API, sessions, desired app state, reconciliation, updates
        |                         |
        |                         +--> signed release and app-catalog verification
        v
systemd user services + rootless Podman: app containers and their networks
        |
        v
Persistent app data and secrets under /var/lib/archipelago

Debian + systemd own the host, boot and protected OS maintenance.
```

The browser UI is in [`neode-ui/`](../neode-ui/). Nginx serves it and routes
API and app traffic. The backend is the `archipelago` crate in
[`core/archipelago/`](../core/archipelago/). The API entry points and RPC
dispatch are under [`api/`](../core/archipelago/src/api/); authentication and
session checks stay on the backend side of the browser boundary.

The backend's [`container/`](../core/archipelago/src/container/) code owns app
lifecycle and reconciliation. The shared [`core/container/`](../core/container/)
crate defines manifest parsing, Podman integration and catalog support.
`apps/<id>/manifest.yml` declares an app; a signed catalog can supply a newer
embedded manifest than the on-disk copy. A container or service being present
does not by itself establish a successful install, healthy app or accepted
release. See [container lifecycle](container-lifecycle.md),
[Quadlet compilation](quadlet-compilation.md) and the
[manifest specification](app-manifest-spec.md).

App databases, wallets, identity and other persistent state live under
`/var/lib/archipelago`. The application runtime and rootless containers must
not gain host package-writer or unrestricted container-engine authority. App
uninstall/update decisions preserve data according to their specific contract;
a test or cleanup must not treat live volumes as disposable. See
[app secrets](secrets.md) and the
[container-store ownership follow-up](container-store-ownership-followup.md).

## Trust and updates

A release manifest and app catalog are verified against the pinned release
root before protected changes. The signed app catalog controls distributed app
metadata; source files in `apps/` are development inputs. The application OTA
path, app activation and OS package/kernel update are separate transactions.
The protected OS updater has its own admission, package custody, reboot and
post-boot verification contract; an application update does not imply an OS
update or a successful new boot. Start with [OS updates](os-updates.md), then
[the OS executor contract](OS-OTA-CONTRACT-20261103.md) when changing that path.

A successful source test, disposable integration run, built artifact, installed
node check and physical/operator acceptance are different levels of evidence.
The current [release and testing index](../Release%20%26%20Testing/README.md)
tracks which level is actually complete. Historical acceptance records remain
version-specific and do not certify a later build.

## Network and node interfaces

The backend's [`fips/`](../core/archipelago/src/fips/),
[`mesh/`](../core/archipelago/src/mesh/),
[`federation/`](../core/archipelago/src/federation/) and
[`transport/`](../core/archipelago/src/transport/) modules own distinct parts
of node connectivity. The Android Companion is in [`Android/`](../Android/).
App network aliases and externally reachable routes have separate admission
and authentication rules. Start with [multi-node architecture](multi-node-architecture.md),
[external access and websites](external-access-and-websites.md) and the
[peering trust model](peering-trust-model.md) for the relevant feature.

The repository also contains an [`openwrt`](../core/openwrt/) crate, image
inputs in [`image-recipe/`](../image-recipe/) and the API's Cloud, wallet,
media and device modules. Their presence in source does not mean every
hardware or installed-node acceptance gate has passed.

## Where to read next

- [Developer guide](developer-guide.md): checkout, builds and safe tests.
- [API reference](api-reference.md): orientation to RPC; verify handlers in source.
- [App developer guide](app-developer-guide.md): packaging and launch acceptance.
- [Documentation index](README.md): current entry points versus dated designs.