Architecture

Marqov has three main components: the platform (web UI and API), the worker (Python execution engine), and Temporal (workflow orchestration).

System Overview

┌─────────────────────────────────────────────────────────┐
│                    User's Browser                        │
│  ┌──────────┐  ┌──────────┐  ┌────────────────────────┐ │
│  │Playground│  │  Jobs UI │  │  Execution Dashboard   │ │
│  │ (Monaco) │  │          │  │  (Gantt, Timeline)     │ │
│  └────┬─────┘  └────┬─────┘  └────────────────────────┘ │
└───────┼──────────────┼──────────────────────────────────┘
        │              │
        ▼              ▼
┌─────────────────────────────────────┐
│       Platform (Next.js)            │
│  ┌─────────┐  ┌──────────────────┐  │
│  │ API     │  │ Supabase         │  │
│  │ Routes  │  │ (Postgres + Auth)│  │
│  └────┬────┘  └──────────────────┘  │
└───────┼─────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────┐
│       Worker (Python)               │
│  ┌──────────────┐  ┌─────────────┐  │
│  │ Job Poller   │  │ Temporal    │  │
│  │              │  │ Executor    │  │
│  └──────┬───────┘  └──────┬──────┘  │
└─────────┼──────────────────┼────────┘
          │                  │
          ▼                  ▼
┌──────────────┐    ┌──────────────────┐
│   Temporal   │    │  Quantum Backend │
│   Server     │    │  (Braket, Azure, │
│              │    │   Local Sim)     │
└──────────────┘    └──────────────────┘

Components

Platform (Next.js)

The web application at marqov.ai. Handles:

• Authentication: Email-based auth via Supabase
• Playground: In-browser code editor with client-side quantum simulation
• Job submission: Creates job records, validates parameters, estimates costs
• Real-time updates: Supabase Realtime subscriptions for live job status
• Execution dashboard: Renders workflow metadata (Gantt chart, task timeline)

The platform does not execute quantum code directly — it delegates to the worker.

Worker (Python)

A long-running Python process deployed as a Docker container on AWS ECS. Handles:

• Job polling: Checks Supabase every 5 seconds for pending jobs
• Script execution: Runs user scripts via exec(), detects @task/@workflow decorators
• Temporal dispatch: Submits workflows to Temporal for orchestrated execution
• Result storage: Updates job records with results, timing, and workflow metadata
• Cost tracking: Calculates actual execution costs based on backend pricing

Temporal

The workflow orchestration engine. Handles:

• Task scheduling: Executes tasks in dependency order, parallelizing independent ones
• Retry logic: Automatically retries failed tasks (configurable per-task)
• Timeout enforcement: Cancels tasks that exceed their timeout
• Execution history: Full audit trail of every workflow execution

Supabase (Postgres)

The database and auth layer. Stores:

• job_runs: Job status, parameters, results, workflow metadata
• scripts: Registered scripts with code and configuration
• backends: Quantum hardware catalog with pricing
• teams: Multi-tenant workspace management
• capsules: Reproducible computation snapshots

Row-Level Security (RLS) ensures teams can only access their own data.

Data Flow: Job Execution

1. User submits a job via the platform UI or API
2. Platform creates a job_runs record with status pending
3. Worker polls and picks up the pending job, sets status to running
4. Worker executes the script, detects @task/@workflow decorators
5. Worker dispatches the workflow to Temporal
6. Temporal executes tasks in dependency order, parallelizing where possible
7. Worker receives the enriched result (output + workflow metadata)
8. Worker stores the result in job_runs.result and metadata in job_runs.workflow_metadata
9. Platform receives the update via Supabase Realtime and renders the execution dashboard

Data Flow: Browser Simulation

For simple circuits, the playground runs simulations entirely in the browser:

1. User writes OpenQASM or Python in the Monaco editor
2. Language is auto-detected
3. QASM is parsed and executed by qulacs-wasm (C++ compiled to WebAssembly)
4. Results render immediately — no server round-trip

This mode supports up to ~20 qubits and is free (no backend costs).

Next steps

• Quickstart — Try it yourself
• Worker Setup — Deploy the worker
• Temporal Configuration — Set up Temporal