QMAX/docs/ARCHITECTURE.md

QMAX Architecture

flowchart LR
    A["Android app<br/>Kotlin + Compose"] -->|HTTPS JSON + uploads| B["QMAX API<br/>ASP.NET Core"]
    A -->|SignalR planned/available| B
    B --> C["SQLite cache<br/>chats/messages/sessions"]
    B --> D["Local storage<br/>attachments/releases"]
    B -->|HTTP internal| E["MAX worker<br/>Python + PyMax"]
    E -->|persistent PyMax session| F["MAX mobile API"]
    B --> G["Caddy TLS<br/>qmax.kusoft.xyz"]

The server is the only public backend surface. The PyMax worker stays inside the Docker network and is controlled through the API/admin page.

Security Rules

• Android pairs to the private server with QMAX_PAIRING_CODE.
• API access uses JWT access tokens and refresh tokens.
• MAX session files live only on the Pi in Docker volumes.
• .env, service-account files, keystores and runtime data are ignored by git.
• Attachments are written as .part first and moved into place only after full upload.
• Android image attachments are downloaded to a local .part cache and exposed to the UI only after size validation.

Current Verified Status

• PyMax login is authorized on the Raspberry Pi worker.
• Chat list, message history, text sending and attachment sending are mapped through pymax-worker/src/server.py.
• Image, video, file and voice attachments are projected through the API and rendered by the Android client.
• Firebase initialization and Android push token registration are enabled for xyz.kusoft.qmax.

Remaining Production Checks

• Keep PyMax session-expiration monitoring active.
• Run an unlocked-device visual pass on the connected phone for every major UI change.
• Replace debug fallback signing with a real release key in android/key.properties.