System architecture
Components and trust boundaries
Last verified 8 August 2026 · source-backed
The platform separates customer interaction, commercial control and privileged infrastructure mutation. Nginx is the public edge; application services bind to loopback unless a narrow runtime endpoint requires otherwise.
Component topology
Direction of control
- Portal sends authenticated server-side calls to whitelisted Mivama Core methods.
- Mivama Core validates ownership and records the requested state.
- A job is created; the root runner pulls it using its integration secret.
- The runner maps the job type to one known playbook. Arbitrary commands are not accepted.
- Progress, final result and discovered runtime manifest are reported to Frappe.
This pull model avoids exposing SSH or Docker privileges through Portal or Frappe HTTP handlers.
Integration boundaries
| Boundary | Authentication | Typical payload |
|---|---|---|
| Browser to Portal | Signed HTTP-only Portal cookie | User actions |
| Portal to Frappe | Portal service secret plus asserted email; Core revalidates ownership | Whitelisted method arguments |
| Stripe to Frappe | Webhook signature and event deduplication | Checkout, subscription, invoice events |
| Runner to Frappe | Runner-specific secret | Job claim, heartbeat, result |
| Portal to Studio | Short-lived one-time launch code | Hosting service identity |
| Studio to Core | Studio integration secret | Redeem/validate/revoke session, resolve target |
| Connector to gateway | Migration-scoped token after one-time code exchange | Manifest and bounded chunks |
Failure philosophy
External events are idempotent where possible. Stripe events have mirror records and retry state; runner jobs have claims and heartbeats; migrations validate legal transitions; Studio deployment makes a verified backup before mutation. A timeout is not treated as permission to assume success.
Source locations
- Portal BFF: app/api/portal, lib/session.ts and lib/portal-api.ts
- Core API: mivama_core/api/portal.py and _portal modules
- Provisioning: mivama_core/provisioning
- Runner: mivama_core/runner/mivama_runner.py
- Studio contracts and workers: packages/contracts and apps/worker