Architecture

System Overview

Metarium AI is a three-layer system. An AI agent talks to a local management server, which signs requests and forwards them to a cloud-hosted CMS.

+------------------------------+
|  AI Agent (Cursor / Vorflux) |
|  Reads AGENTS.md, calls API  |
|  Entry point: mai.net        |
+-------------+----------------+
              | REST (localhost:8420)
              v
+------------------------------+
|  Management Server           |  <- Root of Trust
|  (FastAPI, local only)       |
|  - Key Vault (Substrate)     |
|  - Canonical JSON signing    |
|  - Admin/access orchestration|
+-------------+----------------+
              | Signed HTTPS
              v
+------------------------------+
|  Metarium CMS-AE             |  <- Cloud Data Layer
|  (Flask on App Engine)       |
|  - Google Datastore (NDB)    |
|  - Google Cloud Storage      |
|  - Signature verification    |
+------------------------------+

Management Server

The management server is a FastAPI application on localhost:8420 — the root of trust for the entire system.

• Framework: FastAPI with automatic OpenAPI/Swagger docs at /docs
• Binding: Localhost only — never exposed to the network
• Key Vault: Encrypted Substrate keypairs, decrypted in memory after unlock
• Signing: Canonical JSON encoding before sending to CMS
• Orchestration: CMS installation, admin grants, access control

Key Vault

Password-protected, thread-safe, in-memory Substrate key store.

• Format: PolkadotJS encrypted JSON (same as Polkadot ecosystem)
• Password hashing: Argon2id — memory-hard, GPU/ASIC resistant
• At-rest: Encrypted JSON files, safe for private repos
• Unlock model: POST /vault/unlock decrypts to memory; POST /vault/lock clears
• Password never stored: Used to derive key, then discarded

CMS App Engine

The cloud data layer — a Flask app on Google App Engine that stores and serves content with cryptographic verification.

• Metadata: Google Datastore (NDB)
• Files: Google Cloud Storage with chunked uploads
• Auth: Every write requires a valid signature from a recognized admin key
• Read access: Public or gated by channel configuration

The CMS never holds private keys — it only verifies signatures. Clear separation between authority (local) and data (cloud).

Security Model

API Reference

For interactive docs, visit http://localhost:8420/docs when the server is running. Use GET /help at runtime to discover operations.