Skip to content
MIOSA Docs

Architecture recipes

These recipes map a product responsibility to MIOSA resources.

Use them as starting points, then narrow permissions, data boundaries, and recovery behavior for your product.

Persistent digital operator

Use this pattern for research, operations, support, compliance, recruiting, and revenue agents.

flowchart TB
  App["Customer application"] --> API["Coordinator API"]
  API --> Ledger["Run and responsibility ledger"]
  API --> Sandbox["Sandbox per task"]
  API --> Computer["Persistent computer per identity"]
  Sandbox --> Files["Artifacts and snapshots"]
  Computer --> Sessions["Browser and desktop sessions"]
  Files --> Data["Managed data"]
  Sessions --> Data
  API --> Approval["Approval queue"]
  Approval --> App
  API --> Events["Schedules and webhooks"]
  Events --> API

Core resources

  • One deployed coordinator application.
  • Managed Postgres for responsibilities, runs, approvals, and evidence.
  • Sandboxes for isolated task execution.
  • Computers for persistent authenticated sessions.
  • Object storage for documents, screenshots, and produced artifacts.
  • Connected tools or MCP servers for business systems.

Required controls

  • Idempotency per external action.
  • A checkpoint before waiting or retrying.
  • Explicit approval records for sensitive actions.
  • Attempt-level timeouts and responsibility-level deadlines.
  • Recovery that resumes from state instead of replaying everything.

Agent application builder

Use this pattern when an agent creates software for an end user.

sequenceDiagram
  participant User
  participant Product
  participant Sandbox
  participant Preview
  participant Deploy

  User->>Product: describe the application
  Product->>Sandbox: create from template
  Product->>Sandbox: agent writes and tests code
  Sandbox->>Preview: expose application port
  Preview-->>User: live review URL
  User->>Product: approve candidate
  Product->>Deploy: create immutable release
  Deploy->>Deploy: verify and promote exact release
  Deploy-->>User: stable production URL

Keep preview and production distinct.

A preview is the live sandbox port.

A deployment is an immutable candidate that becomes production only after explicit verification and promotion.

Creative production studio

Use this pattern for image, video, audio, design, and content products.

flowchart LR
  UI["Project workspace"] --> Queue["Generation queue"]
  Queue --> Provider["Connected model provider"]
  Queue --> Worker["Sandbox media worker"]
  Provider --> Storage["Object storage"]
  Worker --> Storage
  Storage --> Review["Review and version history"]
  Review -->|Revise| Queue
  Review -->|Approve| Delivery["Export and delivery"]
  Review --> Database["Project database"]

Store large media outside the application filesystem.

Record model provenance and generation parameters with each output.

Use a computer only for graphical tools that cannot be controlled through a reliable API.

Vertical SaaS with agent workers

Use this pattern when agents support a defined industry workflow.

flowchart TB
  Portal["Branded customer portal"] --> Workflow["Domain workflow service"]
  Workflow --> Records["Business records"]
  Workflow --> Agent["Agent worker"]
  Agent --> Tools["Industry integrations"]
  Agent --> Computer["Customer computer"]
  Workflow --> Review["Authorized reviewer"]
  Review --> Records
  Agent --> Evidence["Evidence and artifacts"]
  Evidence --> Records

The workflow service owns state.

The agent proposes or performs bounded transitions.

The reviewer holds authority for decisions the agent is not allowed to make.

Managed open-source application

Use this pattern to turn an open-source project into a supported cloud product.

flowchart TB
  Upstream["Open-source upstream"] --> Build["Reproducible build"]
  Build --> Candidate["Immutable candidate"]
  Candidate --> Checks["Health, data, route, policy checks"]
  Checks -->|Pass| Rollout["Controlled rollout"]
  Checks -->|Fail| Reject["Keep current release live"]
  Rollout --> Customers["Customer deployments"]
  Customers --> Monitor["Health and drift monitor"]
  Monitor --> Rollback["Rollback controller"]

Do not modify every customer instance directly.

Publish one exact release, roll it through cohorts, verify each deployment automatically, and stop the rollout when an acceptance gate fails.

Model-backed API

Use this pattern for document processing, media generation, embeddings, or private inference.

flowchart LR
  SDK["Customer SDK"] --> API["Deployed API"]
  API --> Auth["Auth, quota, and budget"]
  Auth --> Job["Durable job"]
  Job --> Inference["External or managed inference"]
  Inference --> Output["Result storage"]
  Output --> Callback["Polling, stream, or webhook"]
  Job --> Usage["Usage and evidence"]

The application contract should not depend on one model provider.

Normalize provider errors, cancellation, usage, and output provenance at the job boundary.

Customer isolation choices

ModelGood fitPrimary tradeoff
Shared application and shared databaseHigh-volume SaaS with strong tenant designApplication must enforce every boundary
Shared application and database per customerSensitive data with common application codeMore database lifecycle operations
Deployment per customerCustomization and failure isolationFleet rollout and monitoring complexity
Computer per customerPersistent browser or native software identityHigher runtime cost and recovery responsibility
Workspace per enterpriseStrong administrative and infrastructure boundaryMore provisioning and policy management

Continue into implementation

Was this helpful?