# microsoft/magentic-ui architecture

> Architecture diagram of the GitHub repository microsoft/magentic-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/magentic-ui
- Repository: https://github.com/microsoft/magentic-ui

## Overview

MagenticLite is a human-in-the-loop agentic application for browser automation and local file work. A user starts or selects a session, submits a task, and the backend streams agent progress and results to the frontend; the agent can use browser and filesystem tools, with user approval or takeover for sensitive actions. Session views also expose browser playback and live viewing. The README documents these capabilities; sampled source confirms the app/API structure, agent runtime, model client, and sandboxed browser support. Some route-to-runtime wiring is not shown in the excerpts.

Main entry points: [`src/magentic_ui/teams/omniagent/_omni_agent.py`](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/teams/omniagent/_omni_agent.py) (OmniAgent), [`frontend/src/App.tsx`](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/App.tsx) (App shell), [`frontend/src/components/session/SessionView.tsx`](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/session/SessionView.tsx) (Session view), [`src/magentic_ui/backend/web/app.py`](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/app.py) (FastAPI application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User interface"]
  node_app["App shell<br/>[App.tsx]"]
  node_sessionview["Session view<br/>[SessionView.tsx]"]
  node_chat["Chat interface<br/>[ChatView.tsx]"]
  node_browserui["Browser playback<br/>[BrowserEmbed.tsx]"]
  node_wsmanager["WebSocket manager"]
  node_apiclient["HTTP API client<br/>[client.ts]"]
end

subgraph group_backend["Application backend"]
  node_api["FastAPI application<br/>[app.py]"]
  node_wsroute["WebSocket route<br/>[ws.py]"]
  node_sessionroutes["Session routes<br/>[sessions.py]"]
  node_filesystemroutes["Filesystem routes<br/>[filesystem.py]"]
  node_teammanager["Run manager<br/>[teammanager.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_taskteam["Task team factory<br/>[task_team.py]"]
  node_omniagent["OmniAgent<br/>[_omni_agent.py]"]
  node_websurfer["Web surfer agent"]
  node_approval["Approval controls<br/>[approval.py]"]
end

subgraph group_integrations["Tools and integrations"]
  node_playwright["Browser controller"]
  node_sandbox["Quicksand browser pool"]
  node_hosttools["Host file tools<br/>[_open.py]"]
  node_aiclient["Model client<br/>[_ai_client.py]"]
end

subgraph group_state["Session and settings state"]
  node_database[("Application database<br/>[db_manager.py]")]
end

node_user(("User"))
node_modelservice{{"Model endpoint"}}
node_web{{"Websites"}}
node_filesystem[("Local files")]

node_user -->|"uses"| node_app
node_app -->|"renders"| node_sessionview
node_sessionview -->|"shows"| node_chat
node_sessionview -->|"shows playback"| node_browserui
node_app -->|"provides connections"| node_wsmanager
node_chat -->|"sends tasks"| node_wsmanager
node_wsmanager -->|"streams messages"| node_wsroute
node_app -->|"requests data"| node_apiclient
node_apiclient -->|"calls"| node_api
node_api -->|"dispatches"| node_sessionroutes
node_api -->|"dispatches"| node_filesystemroutes
node_wsroute -->|"runs tasks"| node_teammanager
node_teammanager -->|"creates agent"| node_taskteam
node_teammanager -->|"reads settings"| node_database
node_taskteam -->|"assembles runtime"| node_omniagent
node_omniagent -->|"requests completions"| node_aiclient
node_aiclient -->|"sends prompts"| node_modelservice
node_omniagent -->|"checks actions"| node_approval
node_omniagent -->|"dispatches browser work"| node_websurfer
node_websurfer -->|"controls pages"| node_playwright
node_playwright -->|"uses browser slots"| node_sandbox
node_sandbox -->|"browses"| node_web
node_omniagent -->|"dispatches file work"| node_hosttools
node_hosttools -->|"reads and edits"| node_filesystem

click node_app "https://github.com/microsoft/magentic-ui/blob/main/frontend/src/App.tsx"
click node_sessionview "https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/session/SessionView.tsx"
click node_chat "https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/chat/ChatView.tsx"
click node_browserui "https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/browser/BrowserEmbed.tsx"
click node_wsmanager "https://github.com/microsoft/magentic-ui/blob/main/frontend/src/hooks/useWebSocketManager.tsx"
click node_apiclient "https://github.com/microsoft/magentic-ui/blob/main/frontend/src/api/client.ts"
click node_api "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/app.py"
click node_wsroute "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/ws.py"
click node_sessionroutes "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/sessions.py"
click node_filesystemroutes "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/filesystem.py"
click node_teammanager "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/teammanager/teammanager.py"
click node_taskteam "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/task_team.py"
click node_omniagent "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/teams/omniagent/_omni_agent.py"
click node_websurfer "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/agents/web_surfer/fara/_fara_web_surfer.py"
click node_playwright "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/tools/playwright/playwright_controller_fara.py"
click node_sandbox "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/tools/playwright/browser/quicksand_browser_manager.py"
click node_hosttools "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/teams/omniagent/tools/host/_open.py"
click node_approval "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/approval.py"
click node_aiclient "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/_ai_client.py"
click node_database "https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/database/db_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_sessionview,node_chat,node_browserui,node_wsmanager,node_apiclient,node_user toneBlue
class node_api,node_wsroute,node_sessionroutes,node_filesystemroutes,node_teammanager,node_filesystem toneAmber
class node_taskteam,node_omniagent,node_websurfer,node_approval toneMint
class node_playwright,node_sandbox,node_hosttools,node_aiclient toneRose
class node_database,node_modelservice,node_web toneIndigo
```

## Components

### User interface

- [App shell](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session view](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/session/SessionView.tsx): `frontend/src/components/session/SessionView.tsx`
- [Chat interface](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/chat/ChatView.tsx): `frontend/src/components/chat/ChatView.tsx`
- [Browser playback](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/components/browser/BrowserEmbed.tsx): `frontend/src/components/browser/BrowserEmbed.tsx`
- [WebSocket manager](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/hooks/useWebSocketManager.tsx): `frontend/src/hooks/useWebSocketManager.tsx`
- [HTTP API client](https://github.com/microsoft/magentic-ui/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### Application backend

- [FastAPI application](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/app.py): `src/magentic_ui/backend/web/app.py`
- [WebSocket route](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/ws.py): `src/magentic_ui/backend/web/routes/ws.py`
- [Session routes](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/sessions.py): `src/magentic_ui/backend/web/routes/sessions.py`
- [Filesystem routes](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/web/routes/filesystem.py): `src/magentic_ui/backend/web/routes/filesystem.py`
- [Run manager](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/teammanager/teammanager.py): `src/magentic_ui/backend/teammanager/teammanager.py`

### Agent runtime

- [Task team factory](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/task_team.py): `src/magentic_ui/task_team.py`
- [OmniAgent](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/teams/omniagent/_omni_agent.py): `src/magentic_ui/teams/omniagent/_omni_agent.py`
- [Web surfer agent](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/agents/web_surfer/fara/_fara_web_surfer.py): `src/magentic_ui/agents/web_surfer/fara/_fara_web_surfer.py`
- [Approval controls](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/approval.py): `src/magentic_ui/approval.py`

### Tools and integrations

- [Browser controller](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/tools/playwright/playwright_controller_fara.py): `src/magentic_ui/tools/playwright/playwright_controller_fara.py`
- [Quicksand browser pool](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/tools/playwright/browser/quicksand_browser_manager.py): `src/magentic_ui/tools/playwright/browser/quicksand_browser_manager.py`
- [Host file tools](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/teams/omniagent/tools/host/_open.py): `src/magentic_ui/teams/omniagent/tools/host/_open.py`
- [Model client](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/_ai_client.py): `src/magentic_ui/_ai_client.py`

### Session and settings state

- [Application database](https://github.com/microsoft/magentic-ui/blob/main/src/magentic_ui/backend/database/db_manager.py): `src/magentic_ui/backend/database/db_manager.py`

### Other components

- **User**
- **Model endpoint**
- **Websites**
- **Local files**

## Connections

- User → App shell: uses
- App shell → Session view: renders
- Session view → Chat interface: shows
- Session view → Browser playback: shows playback
- App shell → WebSocket manager: provides connections
- Chat interface → WebSocket manager: sends tasks
- WebSocket manager → WebSocket route: streams messages
- App shell → HTTP API client: requests data
- HTTP API client → FastAPI application: calls
- FastAPI application → Session routes: dispatches
- FastAPI application → Filesystem routes: dispatches
- WebSocket route → Run manager: runs tasks
- Run manager → Task team factory: creates agent
- Run manager → Application database: reads settings
- Task team factory → OmniAgent: assembles runtime
- OmniAgent → Model client: requests completions
- Model client → Model endpoint: sends prompts
- OmniAgent → Approval controls: checks actions
- OmniAgent → Web surfer agent: dispatches browser work
- Web surfer agent → Browser controller: controls pages
- Browser controller → Quicksand browser pool: uses browser slots
- Quicksand browser pool → Websites: browses
- OmniAgent → Host file tools: dispatches file work
- Host file tools → Local files: reads and edits