diff --git a/README.md b/README.md index c4a0228..525d6c0 100644 --- a/README.md +++ b/README.md @@ -27,72 +27,11 @@ ## Architecture at a Glance -```mermaid -flowchart LR - subgraph Clients["Clients"] - CLI["mlis CLI"] - UI["React Console"] - APIClient["External API callers"] - end - - subgraph API["FastAPI Control Plane"] - Auth["AuthN/AuthZ middleware"] - JobsAPI["/v1/jobs"] - WorkerProtocol["/internal worker protocol"] - UIAPI["/console and UI APIs"] - end - - subgraph DB["Postgres Metadata Store"] - Jobs["jobs"] - Assignments["job_assignments"] - WorkersTable["workers (table)"] - Reservations["reservation_transitions"] - Audit["audit_events"] - end - - subgraph Scheduler["Scheduler"] - Ordering["priority, tenant, worker-group ordering"] - Fit["quota and resource fit"] - Placement["worker placement"] - end - - subgraph WorkerPlane["Worker Data Plane"] - Registry["worker registry"] - Lease["heartbeat and lease ownership"] - Runner["runner framework"] - GPU["GPU/resource accounting"] - end - - subgraph Artifacts["Artifact Store"] - Inputs["input payloads"] - Outputs["output results"] - end - - CLI --> API - UI --> API - APIClient --> API - Auth --> JobsAPI - Auth --> WorkerProtocol - JobsAPI --> Jobs - UIAPI --> Jobs - Jobs --> Ordering - Ordering --> Fit - Fit --> Placement - Placement --> Assignments - Assignments --> WorkerPlane - WorkerPlane --> WorkerProtocol - WorkerPlane --> Jobs - Registry -.register / heartbeat.-> WorkersTable - WorkerPlane --> Reservations - JobsAPI --> Inputs - WorkerPlane --> Inputs - WorkerPlane --> Outputs - UIAPI --> Outputs - JobsAPI -.audit state changes.-> Audit - Auth -.audit denials.-> Audit - Lease -.lease expired.-> Assignments - Assignments -.reclaim.-> Ordering -``` +This platform map shows the major control-plane, execution-plane, persistence, +and observability domains. The public demo path is intentionally narrower than +the full platform surface. + +![MLIS platform map](docs/images/platform-map.svg) `/internal/workers` and `/internal/assignments` are worker/data-plane protocol routes, not public user APIs. Users submit and inspect work through `/v1/jobs`, @@ -114,6 +53,11 @@ stateDiagram-v2 CANCELLED --> [*] ``` +This diagram shows the public `job` lifecycle. Execution attempts are modeled +separately as `job_assignments`, which is what makes lease expiry and reclaim +possible without collapsing user intent and worker execution into one state +machine. + Authentication and tenant binding happen in middleware before route handlers. Tenant context comes from the verified token; database queries are filtered by `tenant_id` from `request.state.identity`, not from request bodies. diff --git a/docs/images/platform-map.svg b/docs/images/platform-map.svg new file mode 100644 index 0000000..699fec3 --- /dev/null +++ b/docs/images/platform-map.svg @@ -0,0 +1,183 @@ + + MLIS platform map + A domain map of the MLIS platform showing clients, control plane API, auth and tenant policy, admission control, persistent state, scheduler service, data plane workers, artifacts and IO, observability, and deployment modes. + + + + + + + + MLIS Platform Map + control plane • execution plane • persistence • observability + + + + + HTTP entry + + + + + Clients / Users + + OpenAI SDK / LangChain + + MLIS CLI + + React Console + + Operator / Admin + + entry + + + + + admission and auth + + + + + Control Plane API + + FastAPI App + + Health / Ready / Metrics + + /v1/jobs + + /v1/me + middleware + + Admin / Debug / Invariants + + L1 + + + + + Auth / Tenant / Policy + + JWT mint / verify + + request.state.identity + + tenant from identity + + scoped auth (future) + + security + + + + + persistent state and scheduling + + + + + Admission Control + + job request normalization + + CPU / MEM / GPU / weight caps + + tenant quota admission + + body tenant mismatch guard + + L2 + + + + + Postgres / Persistent State + + jobs + + job_assignments + + workers + + reservation_transitions + + node_resource_ledger + + usage / audit (future) + + db + + + + + scheduler tick and assignment claim + + + + + Scheduler Service + + pending scan + + priority bands + + tenant / GPU fairness + + quota projection + + static / dynamic fit + + GPU device binding + + placement policy + + orchestration + + + + + execution, artifacts, operations + + + + + Data Plane Workers + + register / heartbeat + + claim assignment + + JobWorkerPool + + process runtime + + Docker workload runtime + + vLLM runtime (future) + + finish / report result + + execution + + + + + Artifacts / IO + + local FS artifacts + + input_uri / output_uri + + S3 / MinIO backend (future) + + storage + +