# getmaxun/maxun architecture

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

- Interactive diagram: https://gitdiagram.com/getmaxun/maxun
- Repository: https://github.com/getmaxun/maxun

## Overview

Maxun is a web-data platform for building and running browser-based extraction robots, then retrieving and comparing their outputs. The main workflow runs from the visual dashboard through its API to server-side run orchestration and browser/workflow execution, with persisted results for later review. README-documented branches include AI extraction, scraping, crawling, search, monitoring, document parsing, schedules, and integrations. Some of those implementations were not sampled; their paths and capability links are shown where the tree or README supports them, without asserting unverified internal calls.

Main entry points: [`server/src/task-runner.ts`](https://github.com/getmaxun/maxun/blob/develop/server/src/task-runner.ts) (Run orchestrator), [`server/src/routes/storage.ts`](https://github.com/getmaxun/maxun/blob/develop/server/src/routes/storage.ts) (Robot and run routes), [`src/api/storage.ts`](https://github.com/getmaxun/maxun/blob/develop/src/api/storage.ts) (Dashboard API client), [`server/src/server.ts`](https://github.com/getmaxun/maxun/blob/develop/server/src/server.ts) (HTTP and socket server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Visual dashboard<br/>[MainPage.tsx]"]
  node_frontend_api["Dashboard API client<br/>[storage.ts]"]
  node_run_diff["Run comparison<br/>[useRunDiff.ts]"]
end

subgraph group_api["API and orchestration"]
  node_server["HTTP and socket server<br/>[server.ts]"]
  node_storage_routes["Robot and run routes<br/>[storage.ts]"]
  node_api_entry["Public API routes<br/>[record.ts]"]
  node_task_runner["Run orchestrator<br/>[task-runner.ts]"]
end

subgraph group_execution["Browser and extraction"]
  node_browser_control["Browser sessions<br/>[controller.ts]"]
  node_core_interpreter["Workflow interpreter<br/>[interpret.ts]"]
  node_preprocessor["Workflow preprocessor<br/>[preprocessor.ts]"]
end

subgraph group_data["Persistence and delivery"]
  node_run_records[("Run records<br/>[Run.ts]")]
  node_database[("Database connection<br/>[db.ts]")]
  node_object_storage[("Object storage<br/>[mino.ts]")]
end

subgraph group_capabilities["Product capabilities"]
  node_ai_extraction["AI workflow enrichment"]
  node_markdown_scrape["Page scraping<br/>[scrape.ts]"]
  node_document_extract["Document parsing"]
  node_scheduled_runs["Scheduled runs<br/>[index.ts]"]
  node_sheet_integration["Sheets integration<br/>[gsheet.ts]"]
  node_airtable_integration["Airtable integration<br/>[airtable.ts]"]
  node_search_monitor["Search and monitoring<br/>[storage.ts]"]
end

node_user(("User"))

node_user -->|"build and manage"| node_dashboard_ui
node_dashboard_ui -->|"requests data"| node_frontend_api
node_frontend_api -->|"HTTP requests"| node_storage_routes
node_server -->|"mounts routes"| node_storage_routes
node_server -->|"mounts API"| node_api_entry
node_storage_routes -->|"starts queued runs"| node_task_runner
node_task_runner -->|"creates browser"| node_browser_control
node_task_runner -.->|"executes workflow"| node_core_interpreter
node_core_interpreter -->|"preprocesses workflow"| node_preprocessor
node_task_runner -->|"scrapes pages"| node_markdown_scrape
node_task_runner -->|"exports results"| node_sheet_integration
node_task_runner -->|"exports results"| node_airtable_integration
node_storage_routes -->|"schedules workflow"| node_scheduled_runs
node_storage_routes -->|"creates document robot"| node_document_extract
node_user -.->|"describe extraction"| node_ai_extraction
node_user -.->|"search or monitor"| node_search_monitor
node_task_runner -->|"updates run state"| node_run_records
node_run_records -->|"uses connection"| node_database
node_task_runner -->|"stores outputs"| node_object_storage
node_run_diff -->|"fetches run diff"| node_frontend_api
node_user -.->|"review changes"| node_run_diff

click node_dashboard_ui "https://github.com/getmaxun/maxun/blob/develop/src/pages/MainPage.tsx"
click node_frontend_api "https://github.com/getmaxun/maxun/blob/develop/src/api/storage.ts"
click node_server "https://github.com/getmaxun/maxun/blob/develop/server/src/server.ts"
click node_storage_routes "https://github.com/getmaxun/maxun/blob/develop/server/src/routes/storage.ts"
click node_api_entry "https://github.com/getmaxun/maxun/blob/develop/server/src/api/record.ts"
click node_task_runner "https://github.com/getmaxun/maxun/blob/develop/server/src/task-runner.ts"
click node_browser_control "https://github.com/getmaxun/maxun/blob/develop/server/src/browser-management/controller.ts"
click node_core_interpreter "https://github.com/getmaxun/maxun/blob/develop/maxun-core/src/interpret.ts"
click node_preprocessor "https://github.com/getmaxun/maxun/blob/develop/maxun-core/src/preprocessor.ts"
click node_ai_extraction "https://github.com/getmaxun/maxun/blob/develop/server/src/sdk/workflowEnricher.ts"
click node_markdown_scrape "https://github.com/getmaxun/maxun/blob/develop/server/src/markdownify/scrape.ts"
click node_document_extract "https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/classes/DocumentInterpreter.ts"
click node_scheduled_runs "https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/scheduler/index.ts"
click node_sheet_integration "https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/integrations/gsheet.ts"
click node_airtable_integration "https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/integrations/airtable.ts"
click node_run_records "https://github.com/getmaxun/maxun/blob/develop/server/src/models/Run.ts"
click node_database "https://github.com/getmaxun/maxun/blob/develop/server/src/storage/db.ts"
click node_object_storage "https://github.com/getmaxun/maxun/blob/develop/server/src/storage/mino.ts"
click node_run_diff "https://github.com/getmaxun/maxun/blob/develop/src/hooks/useRunDiff.ts"
click node_search_monitor "https://github.com/getmaxun/maxun/blob/develop/server/src/routes/storage.ts"

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_dashboard_ui,node_frontend_api,node_run_diff,node_user toneBlue
class node_server,node_storage_routes,node_api_entry,node_task_runner toneAmber
class node_browser_control,node_core_interpreter,node_preprocessor toneMint
class node_run_records,node_database,node_object_storage toneRose
class node_ai_extraction,node_markdown_scrape,node_document_extract,node_scheduled_runs,node_sheet_integration,node_airtable_integration,node_search_monitor toneIndigo
```

## Components

### Dashboard

- [Visual dashboard](https://github.com/getmaxun/maxun/blob/develop/src/pages/MainPage.tsx): `src/pages/MainPage.tsx`
- [Dashboard API client](https://github.com/getmaxun/maxun/blob/develop/src/api/storage.ts): `src/api/storage.ts`
- [Run comparison](https://github.com/getmaxun/maxun/blob/develop/src/hooks/useRunDiff.ts): `src/hooks/useRunDiff.ts`

### API and orchestration

- [HTTP and socket server](https://github.com/getmaxun/maxun/blob/develop/server/src/server.ts): `server/src/server.ts`
- [Robot and run routes](https://github.com/getmaxun/maxun/blob/develop/server/src/routes/storage.ts): `server/src/routes/storage.ts`
- [Public API routes](https://github.com/getmaxun/maxun/blob/develop/server/src/api/record.ts): `server/src/api/record.ts`
- [Run orchestrator](https://github.com/getmaxun/maxun/blob/develop/server/src/task-runner.ts): `server/src/task-runner.ts`

### Browser and extraction

- [Browser sessions](https://github.com/getmaxun/maxun/blob/develop/server/src/browser-management/controller.ts): `server/src/browser-management/controller.ts`
- [Workflow interpreter](https://github.com/getmaxun/maxun/blob/develop/maxun-core/src/interpret.ts): `maxun-core/src/interpret.ts`
- [Workflow preprocessor](https://github.com/getmaxun/maxun/blob/develop/maxun-core/src/preprocessor.ts): `maxun-core/src/preprocessor.ts`

### Persistence and delivery

- [Run records](https://github.com/getmaxun/maxun/blob/develop/server/src/models/Run.ts): `server/src/models/Run.ts`
- [Database connection](https://github.com/getmaxun/maxun/blob/develop/server/src/storage/db.ts): `server/src/storage/db.ts`
- [Object storage](https://github.com/getmaxun/maxun/blob/develop/server/src/storage/mino.ts): `server/src/storage/mino.ts`

### Product capabilities

- [AI workflow enrichment](https://github.com/getmaxun/maxun/blob/develop/server/src/sdk/workflowEnricher.ts): `server/src/sdk/workflowEnricher.ts`
- [Page scraping](https://github.com/getmaxun/maxun/blob/develop/server/src/markdownify/scrape.ts): `server/src/markdownify/scrape.ts`
- [Document parsing](https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/classes/DocumentInterpreter.ts): `server/src/workflow-management/classes/DocumentInterpreter.ts`
- [Scheduled runs](https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/scheduler/index.ts): `server/src/workflow-management/scheduler/index.ts`
- [Sheets integration](https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/integrations/gsheet.ts): `server/src/workflow-management/integrations/gsheet.ts`
- [Airtable integration](https://github.com/getmaxun/maxun/blob/develop/server/src/workflow-management/integrations/airtable.ts): `server/src/workflow-management/integrations/airtable.ts`
- [Search and monitoring](https://github.com/getmaxun/maxun/blob/develop/server/src/routes/storage.ts): `server/src/routes/storage.ts`

### Other components

- **User**

## Connections

- User → Visual dashboard: build and manage (evidence: `README.md`)
- Visual dashboard → Dashboard API client: requests data (evidence: `src/pages/MainPage.tsx`)
- Dashboard API client → Robot and run routes: HTTP requests (evidence: `src/api/storage.ts`)
- HTTP and socket server → Robot and run routes: mounts routes (evidence: `server/src/server.ts`)
- HTTP and socket server → Public API routes: mounts API (evidence: `server/src/server.ts`)
- Robot and run routes → Run orchestrator: starts queued runs (evidence: `server/src/routes/storage.ts`)
- Run orchestrator → Browser sessions: creates browser (evidence: `server/src/task-runner.ts`)
- Run orchestrator → Workflow interpreter: executes workflow
- Workflow interpreter → Workflow preprocessor: preprocesses workflow (evidence: `maxun-core/src/interpret.ts`)
- Run orchestrator → Page scraping: scrapes pages (evidence: `server/src/task-runner.ts`)
- Run orchestrator → Sheets integration: exports results (evidence: `server/src/task-runner.ts`)
- Run orchestrator → Airtable integration: exports results (evidence: `server/src/task-runner.ts`)
- Robot and run routes → Scheduled runs: schedules workflow (evidence: `server/src/routes/storage.ts`)
- Robot and run routes → Document parsing: creates document robot (evidence: `server/src/routes/storage.ts`)
- User → AI workflow enrichment: describe extraction (evidence: `README.md`)
- User → Search and monitoring: search or monitor (evidence: `README.md`)
- Run orchestrator → Run records: updates run state (evidence: `server/src/task-runner.ts`)
- Run records → Database connection: uses connection (evidence: `server/src/models/Run.ts`)
- Run orchestrator → Object storage: stores outputs (evidence: `server/src/task-runner.ts`)
- Run comparison → Dashboard API client: fetches run diff (evidence: `src/hooks/useRunDiff.ts`)
- User → Run comparison: review changes (evidence: `README.md`)
