Conversation
There was a problem hiding this comment.
Pull request overview
Adds an architecture page to the mdBook documentation describing the system’s main layers and interactions via a Mermaid diagram.
Changes:
- Added
docs/src/arch.mdwith a Mermaid-based architecture diagram covering client, HTTP API, core engine, WASM runtime, persistence, and deployment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 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"] |
There was a problem hiding this comment.
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.
| TR["Task Routes\nPOST /task/load\nGET /tasks"] | |
| TR["Task Routes\nPOST /api/v0/tasks/{namespace}/{name}/{version}\nGET /api/v0/tasks"] |
| 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 |
There was a problem hiding this comment.
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.
| 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)"] |
There was a problem hiding this comment.
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.
| # Architecture | ||
|
|
There was a problem hiding this comment.
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.
| ```mermaid | ||
| graph TB | ||
| subgraph Client["Client Layer"] |
There was a problem hiding this comment.
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.
| REST["REST Endpoints (:6283)"] | ||
| JR["Job Routes\nPOST /job\nGET /job/:id\nGET /jobs"] | ||
| TR["Task Routes\nPOST /task/load\nGET /tasks"] | ||
| REST --> JR |
There was a problem hiding this comment.
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.
No description provided.