Skip to content

chore(docs): architecture diagram #140

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LeoBorai wants to merge 1 commit into
base: main
Choose a base branch
from
Open

chore(docs): architecture diagram #140

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions docs/src/arch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
# Architecture

Comment on lines +1 to +2
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This page won’t be included in the mdBook navigation unless it’s added to docs/src/SUMMARY.md. Consider adding an entry (e.g., “Architecture”) so readers can discover the diagram in the published docs.

Copilot uses AI. Check for mistakes.
```mermaid
graph TB
subgraph Client["Client Layer"]
Comment on lines +3 to +5
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This Mermaid diagram likely won’t render in the published docs as-is: the repo’s docs build (just docs-build) runs plain mdbook build and there’s no Mermaid preprocessor/config in docs/book.toml. Consider either adding/configuring mdbook-mermaid (and installing it in CI) or replacing this with a pre-rendered SVG/PNG so the “architecture diagram” appears on the site, not just as a code block.

Copilot uses AI. Check for mistakes.
CLI["mate CLI\n(Command-line Interface)"]
end

subgraph API["HTTP API Layer (Axum)"]
REST["REST Endpoints (:6283)"]
JR["Job Routes\nPOST /job\nGET /job/:id\nGET /jobs"]
TR["Task Routes\nPOST /task/load\nGET /tasks"]
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The task endpoints in the diagram appear incorrect. The current API is POST /api/v0/tasks/{namespace}/{name}/{version} (multipart upload) and GET /api/v0/tasks, not POST /task/load and GET /tasks. Please align the diagram with the implemented routes so the docs stay accurate.

Suggested change
TR["Task Routes\nPOST /task/load\nGET /tasks"]
TR["Task Routes\nPOST /api/v0/tasks/{namespace}/{name}/{version}\nGET /api/v0/tasks"]

Copilot uses AI. Check for mistakes.
REST --> JR
Comment on lines +10 to +13
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The API routes shown here don’t match the current Axum routes. The server nests under /api/v0 and exposes jobs at POST /api/v0/jobs + GET /api/v0/jobs (with ?id= for lookup), not POST /job / GET /job/:id / GET /jobs. Updating the diagram to the real paths will prevent clients from implementing against incorrect endpoints.

Copilot uses AI. Check for mistakes.
REST --> TR
end

subgraph Core["Core Engine"]
SCHED["Scheduler\n(Tokio async runtime)"]
JQ["Job Queue\n(In-memory + persisted)"]
EXEC["WASM Executor"]
end

subgraph WasmRuntime["WASM Runtime Layer (Wasmtime)"]
ENG["Engine\n(Cranelift JIT)"]
STORE["Store\n(per-job sandboxed state)"]
LINKER["Linker\n(host function bindings)"]
MOD["Module\n(compiled .wasm)"]
INST["Instance\n(isolated execution)"]
Comment on lines +23 to +28
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The WASM runtime box labels a Module (compiled .wasm), but the executor currently uses Wasmtime’s component model (wasmtime::component::Component) rather than wasmtime::Module. Consider renaming this node to “Component” (and adjusting any related labels) so the diagram matches the actual runtime objects being instantiated.

Copilot uses AI. Check for mistakes.
ENG --> STORE
ENG --> LINKER
ENG --> MOD
LINKER --> INST
MOD --> INST
STORE --> INST
end

subgraph TaskRepo["Task Repository"]
TREG["Task Registry\n(namespace/name@version)"]
WASM["Stored .wasm Binaries"]
TREG --> WASM
end

subgraph Persistence["Persistence Layer (SQLx + PostgreSQL)"]
DB[("PostgreSQL\nDatabase")]
JOBS_T["jobs table\n(id, task_id, args, status,\nscheduled_at, result)"]
TASKS_T["tasks table\n(id, namespace, name,\nversion, wasm_bytes)"]
DB --> JOBS_T
DB --> TASKS_T
Comment on lines +43 to +48
Copy link

Copilot AI Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The persistence section doesn’t reflect the current implementation. Storage uses SQLx with SQLite (not PostgreSQL), and the only migration creates a jobs table with columns like name, task, scheduled_at, attempts, etc. (no tasks table / wasm_bytes, and not task_id). Either update this to SQLite + the actual schema, or reword it as an aspirational/roadmap architecture to avoid misleading readers.

Copilot uses AI. Check for mistakes.
end

subgraph Docker["Deployment (Docker)"]
IMG["ghcr.io/leoborai/mate:latest\n(port 6283)"]
end

CLI -->|"HTTP requests"| REST
JR --> SCHED
TR --> TREG
SCHED --> JQ
JQ -->|"dispatch at scheduled_at"| EXEC
EXEC -->|"load task binary"| TREG
EXEC --> ENG
INST -->|"job result / error"| JQ
TREG <-->|"read/write wasm"| TASKS_T
JQ <-->|"persist state"| JOBS_T

classDef layer fill:#1e3a5f,stroke:#4a90d9,color:#ffffff,rx:6
classDef component fill:#0d2137,stroke:#4a90d9,color:#c8d8e8,rx:4
classDef db fill:#1a3a1a,stroke:#4caf50,color:#c8e8c8,rx:4
classDef wasm fill:#3a1a3a,stroke:#9c27b0,color:#e8c8e8,rx:4
classDef docker fill:#1a2a3a,stroke:#2196f3,color:#c8d8f8,rx:4

class Client,API,Core,TaskRepo,Persistence,Docker layer
class CLI,REST,JR,TR,SCHED,JQ,EXEC,TREG,WASM,IMG component
class DB,JOBS_T,TASKS_T db
class ENG,STORE,LINKER,MOD,INST,WasmRuntime wasm

```