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

# System Architecture

TaτsuOS is composed of three codebases, each of which can be deployed and operated independently.

### 1. tatsuos-burn — Smart Contracts and Burn Portal

A Solidity contract suite (`TatsuBurn.sol`, plus interfaces) deployed to Ethereum-compatible chains. It accepts a TATSU burn for a registered `featureId` against a specified `deviceId`, and emits a `FeatureUnlocked(user, featureId, deviceId, amount, nonce)` event. A nonce registry prevents replay.

A React + Vite portal provides the end-user interface: connect wallet, select feature, enter device ID, approve, burn. After confirmation, the portal pulls the signed receipt from the cloud API and pushes it to the device over Web Bluetooth.

### 2. tatsuos-cloud — Listener, Signer, and Dashboard

A Next.js application that hosts:

* `FeatureUnlocked` chain listener subscribing to events over a JSON-RPC websocket.
* A receipt signer that constructs a canonical receipt payload and signs it with an ECDSA private key held in a KMS / HSM in production.
* A TimescaleDB instance (Postgres-compatible) for telemetry and unlock history.
* An MQTT subscriber (EMQX broker) for device-originated heartbeat and telemetry.
* A web dashboard for fleet operators to monitor devices, online status, and unlock history.
* A public, unauthenticated `/api/receipt?deviceId=…` endpoint that returns signed receipts. Because every receipt is self-authenticating, this endpoint requires no access control.

### 3. tatsuos-firmware — Zephyr RTOS Image

A Zephyr-based firmware image targeting the ESP32 family in the initial release, with a board-abstraction layer designed to extend to nRF52, STM32, and RP2040 platforms. The image includes:

* WiFi station and provisioning.
* MQTT client for telemetry and heartbeat publishing.
* BLE GATT server exposing a `ReceiptCharacteristic` for receipt delivery.
* ECDSA verification using the device's hardware crypto engine where available, with a software fallback (tinycrypt or mbedTLS).
* A persistent, append-only `feature_unlocks` partition in flash.
* A small in-process ML hook (the `ml/` module) reserved for on-device inference workloads that may themselves be feature-gated.

### 4. Architectural Diagram

```
┌─────────────┐    burn TATSU          ┌──────────────┐
│  User /     │──────────────────────► │  TatsuBurn   │
│  Portal     │                        │  Contract    │
└──────┬──────┘                        └──────┬───────┘
       │                                      │
       │ HTTPS                                │ FeatureUnlocked event
       ▼                                      ▼
┌─────────────┐    signed receipt      ┌──────────────┐
│ /api/       │◄───────────────────────│  Listener    │
│ receipt     │                        │  + Signer    │
└──────┬──────┘                        └──────────────┘
       │
       │ HTTPS → phone → BLE GATT
       ▼
┌─────────────┐    ECDSA verify        ┌──────────────┐
│  Firmware   │──────────────────────► │  Hardcoded   │
│  (Zephyr)   │                        │  Public Key  │
└─────────────┘                        └──────────────┘
```