# magnitudedev/magnitude architecture

> Architecture diagram of the GitHub repository magnitudedev/magnitude, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/magnitudedev/magnitude
- Repository: https://github.com/magnitudedev/magnitude

## Overview

##### Project type and purpose
- This is a monorepo (TurboRepo) housing an open‑source end‑to‑end testing framework (“Magnitude”) powered by AI agents.
- It exposes a CLI/test‑runner (magnitude-test), core agent logic (magnitude-core), a remote agent transport layer (magnitude-remote), and a hosted backend service (magnitude-mcp). There’s also an `infra/modal` folder for self‑hosting on Modal.

##### File structure
- Top‑level:
- packages/
– magnitude-core (agent logic, CLI entry point, recipe model)
– magnitude-test (test-case compiler, discovery, renderer, runner CLI)
– magnitude-remote (client/server for remote agent execution)
– magnitude-mcp (hosted API server + tool services)
- infra/modal (Python scripts & configs for self‑hosting on Modal)
- assets (demo gif)
- configs: package.json, turbo.json, tsconfigs, .dockerignore, .gitignore
- Patterns:
- Each package is an isolated Node/TS module.
- magnitude-test compiles and discovers `*.mag.ts` files, then invokes either a LocalRunner or RemoteRunner.
- LocalRunner uses magnitude-core directly; RemoteRunner communicates with magnitude-remote server.
- magnitude-mcp is a standalone Node service exposing REST/gRPC endpoints for the hosted offering.

##### README for additional insights
- Core features: planning agent (LLM), execution agent (visual/browser), natural‑language DSL.
- Two deployment modes: Hosted (calls mcp service + managed infra) vs Self‑hosted (deploy your own mcp/remote agent + browser infra + LLM provider).

1. Developer Workstation
- magnitude-test CLI
- Test files (`*.mag.ts`)
2. Local Execution Path
- magnitude-core (planning & execution agents)
- Browser Infra (Playwright / headless Chrome)
- LLM Provider (OpenAI, Anthropic, etc.)
3. Remote Execution Path (Self‑hosted)
- magnitude-test RemoteRunner
- magnitude-remote Server & Observer/Tunnel
- magnitude-core (agent logic runs in remote)
- Browser Infra & LLM Provider
4. Hosted Service Path
- magnitude-test RemoteRunner → magnitude-mcp API
- magnitude-mcp (API server, toolService)
- Managed LLM Infra (proprietary)
- Managed Browser Infra (Modal / proprietary)
5. infra/modal (optional)
- Scripts to deploy self‑hosted magnitude-remote & magnitude-core on Modal

- CLI “npx magnitude”:
- Discovers tests → compiles → invokes Runner
- LocalRunner → magnitude-core → LLM Provider & Browser → returns results
- RemoteRunner → HTTP/WebSocket → magnitude-remote Server → spawns magnitude-core + Browser → streams back events
- Hosted: RemoteRunner → magnitude-mcp API → orchestrates internal magnitude-core + Modal browser + LLM → returns logs/results

c. Architectural patterns & principles:
- Monorepo with isolated packages (clear boundaries).
- Plug‑in runner strategy (Local vs Remote).
- Separation of concerns:
- magnitude-test (test orchestration)
- magnitude-core (agent intelligence)
- magnitude-remote (transport)
- magnitude-mcp (hosted backend).
- Dependency‐injection of LLM and browser infra for self‑hosting vs managed hosting.

d. Key technologies & frameworks:
- Node.js / TypeScript, Turborepo for monorepo management
- Playwright / headless Chrome for visual execution
- REST/WebSocket for remote communication
- Modal for serverless deployment (infra/modal)
- Various LLM providers via HTTP APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation" 
        direction TB
        CLI["magnitude-test CLI"]:::developer
        TestFiles["Test Files (*.mag.ts)"]:::developer
    end

    CLI -->|"discover & compile"| Discovery["Test Discovery"]:::developer
    click CLI "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/index.ts"
    click CLI "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/runner/cli.ts"
    click TestFiles "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/example/tests/example.mag.ts"
    click TestFiles "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/example/tests/magnitude.config.ts"
    click Discovery "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/discovery/testCaseBuilder.ts"
    click Discovery "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/discovery/testDeclaration.ts"
    click Discovery "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/discovery/testRegistry.ts"
    click Discovery "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/discovery/types.ts"
    click Discovery "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/discovery/util.ts"

    Discovery -->|"compile"| Compiler["Test Compiler"]:::developer
    click Compiler "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/compiler/index.ts"

    Compiler -->|"render"| Renderer["Test Renderer"]:::developer
    click Renderer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/renderer/index.ts"
    click Renderer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/renderer/colors.ts"
    click Renderer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/renderer/suiteViewer.ts"
    click Renderer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/renderer/testRenderer.ts"

    Renderer --> RunnerChoice{"Choose Runner"}:::developer

    %% Local Execution Path
    subgraph "Local Execution Path" 
        direction TB
        LocalRunner["LocalRunner"]:::developer
        Core["magnitude-core Agent"]:::core
        Browser["Browser Infra"]:::external
        LLM["LLM Provider"]:::external
    end

    RunnerChoice -->|"LocalRunner"| LocalRunner
    click LocalRunner "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/runner/localRunner.ts"
    LocalRunner -->|"invoke"| Core
    click Core "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-core/src/cli.ts"
    click Core "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-core/src/agent.ts"
    click Core "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-core/src/index.ts"
    click Core "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-core/src/recipe/recipe.ts"
    click Core "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-core/src/recipe/types.ts"
    Core -->|"uses"| Browser
    Core -->|"calls"| LLM

    %% Remote Self-Hosted Path
    subgraph "Remote Execution Path (Self-hosted)" 
        direction TB
        RemoteRunner["RemoteRunner"]:::developer
        RemoteServer["magnitude-remote Server"]:::service
        RemoteCore["magnitude-core Agent"]:::core
        RBrowser["Browser Infra"]:::external
        RLLM["LLM Provider"]:::external
        Observer["Observer/Tunnel"]:::service
    end

    RunnerChoice -->|"RemoteRunner"| RemoteRunner
    click RemoteRunner "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/runner/remoteRunner.ts"
    RemoteRunner -->|"HTTP/WebSocket"| RemoteServer
    click RemoteServer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-remote/src/index.ts"
    click RemoteServer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-remote/src/client/agent.ts"
    click RemoteServer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-remote/src/server/index.ts"
    click RemoteServer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-remote/src/server/observer.ts"
    click RemoteServer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-remote/src/server/tunnel.ts"
    click RemoteServer "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-remote/src/server/types.ts"
    RemoteServer -->|"spawns"| RemoteCore
    RemoteCore -->|"uses"| RBrowser
    RemoteCore -->|"calls"| RLLM

    %% Hosted Service Path
    subgraph "Hosted Service Path" 
        direction TB
        HostedRunner["RemoteRunner"]:::developer
        MCP["magnitude-mcp API"]:::service
        MCPCore["magnitude-core Agent"]:::core
        MBrowser["Managed Browser Infra"]:::external
        MLLM["Managed LLM Infra"]:::external
    end

    RunnerChoice -->|"Hosted"| HostedRunner
    click HostedRunner "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-test/src/runner/remoteRunner.ts"
    HostedRunner -->|"HTTP API"| MCP
    click MCP "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-mcp/src/index.ts"
    click MCP "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-mcp/src/server.ts"
    click MCP "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-mcp/src/toolService.ts"
    click MCP "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-mcp/src/tools.ts"
    click MCP "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-mcp/src/test.ts"
    click MCP "https://github.com/magnitudedev/magnitude/blob/main/packages/magnitude-mcp/src/schemas.ts"
    MCP -->|"orchestrates"| MCPCore
    MCPCore -->|"uses"| MBrowser
    MCPCore -->|"calls"| MLLM

    %% Infra Modal
    infra["infra/modal (Modal deployment)"]:::infra
    click infra "https://github.com/magnitudedev/magnitude/blob/main/infra/modal/README.md"
    click infra "https://github.com/magnitudedev/magnitude/blob/main/infra/modal/download_molmo.py"
    click infra "https://github.com/magnitudedev/magnitude/blob/main/infra/modal/molmo_vllm.py"

    infra --> RemoteServer
    infra --> MCP

    classDef developer fill:#cce5ff,stroke:#004085,color:#004085;
    classDef core fill:#d4edda,stroke:#155724,color:#155724;
    classDef service fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#6c757d;
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
```
