# 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  │
└─────────────┘                        └──────────────┘
```


---

# 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:

```
GET https://tatsu.gitbook.io/tatsu-whitepaper/system-architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.