> For the complete documentation index, see [llms.txt](https://docs.bosonnetwork.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bosonnetwork.io/core-concepts/architecture.md).

# Architecture Overview

Boson Network has a **two-layer design**. Layer 1 is a distributed hash table that provides decentralized routing, storage, and identity. Layer 2 is a set of application services that run on top of the DHT and are discoverable through it. The two layers are deliberately independent: the DHT works without any services running, and services can be added or removed without changing the DHT protocol.

## Layer 1 — Boson DHT

The foundation of the network is a Kademlia DHT node (`KadNode`) that runs over **UDP on port 39001** by default. Every participant — server, desktop, or mobile — that runs a full DHT node is identified by a 256-bit `Id` derived from an Ed25519 public key. The DHT provides three primitives:

| Primitive         | RPC pair                      | What it stores                                             |
| ----------------- | ----------------------------- | ---------------------------------------------------------- |
| Node routing      | `FIND_NODE`                   | `NodeInfo` — IP address + port of a peer                   |
| Value storage     | `STORE_VALUE` / `FIND_VALUE`  | Arbitrary blobs — immutable, mutable, or encrypted         |
| Peer announcement | `ANNOUNCE_PEER` / `FIND_PEER` | `PeerInfo` — a service endpoint registered by a super node |

Because every Id is derived from a public key, any stored value or service announcement can be cryptographically tied to its owner. There are no usernames, email addresses, or central registries in Layer 1.

## Layer 2 — Application Services

Layer-2 services run on **super nodes** (servers with a public IP). Each service has its own Ed25519 key pair and announces itself into the DHT with `ANNOUNCE_PEER` so clients can find it with a `FIND_PEER` lookup using the service's well-known peer ID. No hard-coded IP addresses are needed.

The four built-in services are:

```
  Layer 2 — Application Services
  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
  │ web-gateway  │  │  messaging   │  │  ion-store   │  │ active-proxy │
  │  (HTTPS)     │  │  (MQTTS)     │  │  (HTTPS)     │  │  (TCP)       │
  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘
            │               │                │                 │
            └───────────────┴────────────────┴─────────────────┘
                                     │
  Layer 1 — Boson DHT (KadNode)      │  announces/discovers via FIND_PEER
  ┌──────────────────────────────────────────────────────────────────────┐
  │  Kademlia DHT  ·  Ed25519 peer identity  ·  UDP port 39001           │
  │  FIND_NODE  ·  FIND_VALUE / STORE_VALUE  ·  FIND_PEER / ANNOUNCE     │
  └──────────────────────────────────────────────────────────────────────┘
```

## The Director

A **Director** is the supervisor process that manages a super node. It:

* Starts and stops the `KadNode` (DHT node) using `node.yaml`.
* Discovers and starts all layer-2 services declared in `services.d/` YAML files.
* Manages user accounts, registered devices, and subscriptions in a SQLite or PostgreSQL database.
* Keeps the accounts that **CBOR Web Tokens (CWTs)** are checked against, and issues tokens to clients that sign in.
* Manages **federation** with peer super nodes: Directors exchange signed proposals and share service registrations.
* Maintains a **blacklist** of misbehaving DHT nodes.
* Optionally exposes a **Prometheus metrics** endpoint.
* Serves a built-in **admin dashboard** (`/admin/`) and **user portal** (`/portal/`).

The Director listens on an HTTP(S) port (default `9000`) and exposes separate API paths for client applications, administrator operations, and inter-node federation.

## Client Roles

Clients interact with Boson in one of two ways:

**Regular Nodes (native apps)** run a full `KadNode` themselves. They participate directly in DHT routing and can talk to layer-2 services over their native protocols.

**Light Nodes** do not run a DHT node. They reach the network through the `web-gateway` service, which translates HTTP requests into DHT operations (`FIND_NODE`, `FIND_VALUE`, `STORE_VALUE`, `FIND_PEER`, `ANNOUNCE_PEER`) on the caller's behalf.

## Authentication

Every layer-2 service validates requests using a **CWT**. A CWT is a CBOR-encoded COSE\_Sign1 structure signed with the client's Ed25519 private key. The service checks the signature against the client's DHT public key — no password database, no OAuth server, no CA certificate. See [Authentication: CBOR Web Tokens](/core-concepts/authentication-cwt.md) for details.

## TLS

A super node serves TLS with either a certificate from a public authority or a self-signed certificate bound to the node's Ed25519 identity. Boson clients verify a self-signed certificate against the identity they expect rather than against an authority, so a node needs no certificate authority to be secure. See [Security Model](/core-concepts/security-model.md).

## Further Reading

* [Node Types](/core-concepts/node-types.md) — Super, Regular, and Light explained with a comparison table.
* [Kademlia DHT](/core-concepts/kademlia-dht.md) — how the DHT protocol works.
* [DHT Data Model](/core-concepts/data-model.md) — nodes, values, and peers in detail.
* [Layer-2 Services Overview](/core-concepts/services.md) — the four built-in services.
* [Federation](/core-concepts/federation.md) — how super nodes peer with each other.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bosonnetwork.io/core-concepts/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.