OSGAccountServer/docs/ARCHITECTURE.md

OSGAccountServer architecture

OSGAccountServer is a modular Ktor application. It owns OSG accounts, credits, referrals, integrity checks, and metered access to OSG-hosted providers.

It does not replace the app's local ASR, BYOK provider access, or iCloud sync.

Trust boundaries

1. Sign in with Apple identifies a user. The service stores only Apple's stable subject, encrypted Apple refresh credentials, and internal identifiers.
2. The host app owns account-management credentials in its private Keychain.
3. The keyboard extension receives a separately revocable gateway grant. That grant cannot delete an account, redeem referrals, or mutate credits directly.
4. Provider credentials exist only in the server process.
5. Audio and text are transient request data. They must not be persisted or included in logs, traces, metrics labels, or error messages.

Modules

• auth verifies Apple credentials and manages rotating application sessions.
• account reads and deletes accounts.
• appleevents handles consent and account lifecycle notifications.
• credits owns the immutable ledger and its balance projection.
• referrals binds one inviter and awards both users after qualified usage.
• integrity evaluates DeviceCheck and App Attest evidence.
• gateway proxies Volcengine ASR and DeepSeek text requests.
• inviteweb serves the first-party invitation landing page.
• analytics accepts a strict allowlist of product event metadata and links a pseudonymous installation to an account only when a valid session is present.
• admin/stats combines accepted product events with authoritative billing, StoreKit, account, and referral aggregates for the internal dashboard.

Modules communicate through narrow ports. Provider clients, Apple clients, integrity clients, clocks, token generators, and repositories are replaceable in tests.

Monetary invariants

• Credit amounts are signed 64-bit integers; public inputs never accept decimal credit values.
• Ledger rows are immutable.
• Every mutation has a unique idempotency key.
• Available and reserved balances never become negative.
• Reservation, settlement, release, refund, and referral rewards run in database transactions with the account rows locked.
• A referral can transition to rewarded exactly once.
• Usage records reference the exact rate-card version used for settlement.

Hosted request lifecycle

1. Authenticate a gateway-scoped principal and verify request integrity.
2. Validate payload size and feature-specific policy.
3. Reserve the maximum expected credits.
4. Call the allowlisted upstream provider.
5. Settle from provider usage or server-observed ASR duration.
6. Release on transport/provider failure or empty output.
7. Qualify a pending referral only after a successful non-zero settlement.

Data retention

• No audio, transcript, prompt, context, or generated response body is stored.
• Authentication and integrity payloads are retained only as hashes or validated claims required for replay protection.
• Usage metadata contains feature, model, metering units, latency, status, and rate-card version.
• Product events contain enums, release versions, timestamps, and duration buckets only. Installation UUIDs are stored as SHA-256 digests.
• Operational logs use request IDs and internal opaque IDs, never Apple subjects or bearer credentials.
• Account deletion revokes credentials and cascades through linked product installations and events. Only non-identifying aggregate service metrics may remain.