Repository navigation
Architecture Diagrams
These views follow C4's progression from the system and its users to the applications and data stores inside it. A C4 container is a running application or data store; it does not necessarily mean a Docker container. The source uses Mermaid's C4Context and C4Container syntax so the diagrams can display directly on a GitHub Wiki page.
Scope: the implemented hosted evaluation/reporting path at public revision 3567263. Direct Harbor use and the older Bun fixture runner are omitted from these views. The presentation-export extension is shown separately to keep the evaluation view readable.
| Symbol / convention | Meaning |
|---|---|
| Person silhouette | A human role, not a software process |
| Blue system box | Heval, the software system being described |
| Blue container rectangle | A Heval application or runtime responsibility, with its technology and purpose |
| Cylinder | Persistent data store; the label identifies database, filesystem, or blob storage |
| Gray external-system box | A service outside Heval's ownership |
| Labeled boundary | Groups applications/data within Heval's scope; it is not a firewall, VM, or deployment replica |
| Directed labeled arrow | Source uses/calls/writes to the destination. The label states the operation and, in container views, the transport. Responses return over that interaction unless separately explained |
Color is supplementary: names, stereotypes, and descriptions also identify each element. Arrows express dependencies/interactions rather than elapsed time; use the numbered walkthrough below for execution order. The key applies to all three views.
Question answered: Who uses Heval, and what external services does it rely on?
%%{init: {"c4": {"c4ShapeMargin": 95, "diagramMarginY": 15}}}%%
C4Context
title Heval - System Context
Person(evaluator, "Evaluator / operator", "Configures comparisons and connects a worker")
Person(reader, "Report reader", "Reviews an invited or published report")
System(heval, "Heval", "Coordinates evaluations and explains their results")
System_Ext(identity, "WorkOS", "User identity service")
System_Ext(models, "Model providers via Merge Gateway", "Remote inference for coding agents")
Rel(evaluator, heval, "Configures runs and analyzes results")
Rel(reader, heval, "Views authorized reports")
Rel(heval, identity, "Authenticates workspace users")
Rel(heval, models, "Requests model inference during trials")
UpdateRelStyle(evaluator, heval, $offsetX="-80", $offsetY="0")
UpdateRelStyle(reader, heval, $offsetX="30", $offsetY="-35")
UpdateRelStyle(heval, identity, $offsetX="-75", $offsetY="-30")
UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")
Heval includes the web workspace and its connected execution software, even though they run on different machines. The evaluator can also be the worker operator; those roles need not be different people. Invited collaborators sign in; an anonymous reader can use an explicitly published share link. Such a link grants no worker control.
Vercel, Convex, and Docker are hosting/runtime technologies of the solution, so their details appear at container level rather than as additional user-facing systems here. The model-provider box includes the gateway and its downstream serving provider; model and vendor identity are recorded per study.
Question answered: Which applications and stores implement Heval, and how do they communicate?
%%{init: {"c4": {"c4ShapeMargin": 95, "diagramMarginY": 15}}}%%
C4Container
title Heval - Evaluation and Reporting Containers
Person(user, "Evaluator / reader", "Uses the web workspace")
System_Ext(auth, "WorkOS", "Sign-in and identity tokens")
System_Boundary(heval, "Heval") {
Container(web, "Web workspace", "React / TypeScript; Vercel", "Configure, inspect, edit and share")
Container(api, "Workspace backend", "Convex functions", "Ownership, queue, reports and sharing")
ContainerDb(db, "Workspace data", "Convex database", "Machines, claims, reports and revisions")
Container(daemon, "Connected runner", "Node.js on Linux", "Polls, claims and uploads results")
Container(supervisor, "Job supervisor", "Node.js on Linux", "Owns execution and deadline")
Container(execution, "Evaluation runtime", "Harbor / Python / Docker", "Task, coding harness and verifier")
ContainerDb(files, "Worker files", "Linux filesystem", "Profiles, task snapshots and raw results")
}
System_Boundary(providers, "External inference services") {
System_Ext(gateway, "Model providers", "Merge Gateway and serving vendor")
}
Rel(user, web, "Uses", "HTTPS")
Rel(web, auth, "Signs in", "HTTPS")
Rel(web, api, "Submits and observes work", "Convex client / TLS")
Rel(api, db, "Reads and writes", "Convex transactions")
Rel(daemon, api, "Claims work; uploads status/results", "Outbound HTTPS")
Rel(daemon, supervisor, "Starts and recovers jobs", "Local process / state files")
Rel(supervisor, execution, "Executes approved task profile", "Local process / Docker API")
Rel(execution, files, "Writes raw trial artifacts", "Filesystem")
Rel(daemon, files, "Reads profiles and saved outcomes", "Filesystem")
Rel(supervisor, files, "Normalizes results; saves outcome", "Filesystem")
Rel(execution, gateway, "Harness requests inference", "HTTPS")
UpdateRelStyle(web, api, $offsetX="-75", $offsetY="-45")
UpdateRelStyle(api, db, $offsetX="-60", $offsetY="-45")
UpdateRelStyle(daemon, supervisor, $offsetX="-75", $offsetY="-45")
UpdateRelStyle(supervisor, execution, $offsetX="-80", $offsetY="-45")
UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")
- Web workspace: Vercel serves the frontend assets, which run in the browser. Private operations carry the signed-in identity to Convex; the backend verifies tokens and applies access rules. The WorkOS arrow summarizes the sign-in flow, not a database of user passwords inside Heval.
- Backend and data: functions and database are logical C4 containers on the same managed Convex platform. They are not separate servers Heval operates. The persistent run records act as the work queue; there is no separate Redis or message-broker service in this path.
- Worker boundary: daemon, supervisor, runtime, and worker files are co-located on a trusted Linux worker. They are drawn within Heval's logical system boundary, which spans cloud and worker deployments. The daemon initiates the cloud connection; the cloud does not open an inbound connection to the worker.
- Runtime grouping: the evaluation-runtime box groups Harbor's process and its disposable Docker task processes at this level. Inside it, the harness changes candidate code and the task verifier grades it. Harbor is an external dependency packaged into the execution path, not a custom Heval benchmark engine.
- Supervisor: task snapshotting, filtered execution environment, deadline enforcement, and local outcome recording belong here. The polling daemon can reconnect to its work. This diagram summarizes local file interactions; it does not depict every file read/write as a separate arrow.
- Data upload: the runtime writes raw artifacts locally. The supervisor normalizes and validates report data from those artifacts, then saves the outcome locally. The daemon uploads that saved sanitized report through the backend. Raw traces and provider credentials are not uploaded as report attachments.
- Deployment requirements: the connected execution components require an operator-controlled Linux machine or VM with Docker access. The browser can run on another OS. This logical architecture does not depend on a developer's personal host or virtualization setup.
- The user queues an approved selection through the web workspace.
- The backend saves the experiment and child-run state transactionally.
- The daemon polls, claims a run, and launches the independent supervisor.
- The supervisor invokes Harbor; the harness uses the model provider and the verifier grades the candidate.
- The supervisor normalizes the report and saves its outcome; the daemon reads that outcome and uploads the sanitized report to the backend.
- The web workspace observes the saved results and opens the combined report. Publishing a revision is a separate user action.
Question answered: How can an image export complete after the browser closes?
%%{init: {"c4": {"c4ShapeMargin": 95, "diagramMarginY": 15}}}%%
C4Container
title Heval - Private Presentation Export Containers
Person(owner, "Authorized report member", "Requests and downloads an export")
System_Boundary(exports, "Heval - export path") {
Container(studio, "Studio", "React / Vercel", "Saves presentation and requests export")
Container(jobs, "Export coordinator", "Convex functions and Node action", "Claims persisted job and runs renderer")
Container(renderer, "Renderer", "Chromium / Vercel Sandbox", "Renders PNG or ZIP from saved inputs")
ContainerDb(blob, "Export files", "Private Vercel Blob", "Stores generated images and ZIPs")
Container(download, "Download endpoint", "Vercel function", "Checks current access and streams file")
}
Rel(owner, studio, "Requests export", "HTTPS")
Rel(studio, jobs, "Saves and queues immutable input", "Convex client / TLS")
Rel(jobs, renderer, "Runs renderer and reads output", "Sandbox API / HTTPS")
Rel(jobs, blob, "Uploads completed artifact", "Blob API / HTTPS")
Rel(studio, download, "Downloads with access token", "HTTPS")
Rel(download, jobs, "Checks current report access", "Convex API / HTTPS")
Rel(download, blob, "Reads private artifact", "Blob API / HTTPS")
UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1")
The export coordinator is part of the same Convex backend in the main view; it persists export inputs/status in the same workspace database, omitted here to reduce repetition. A scheduled action starts the renderer from a pinned snapshot, retrieves the output, writes it to private Blob storage, and stops the Sandbox. The renderer receives no provider credentials and denies outbound networking. Sharing a report does not make its private export-download endpoint public. This path renders presentations; it does not execute Harbor benchmarks.
How an evaluation works adds the submission-to-publication sequence diagram, a six-trial example, and recovery cases. The sequence identifies execution order; the C4 views above identify responsibilities and dependencies.
- C4 system context describes people and external systems around the system being designed.
- C4 container view decomposes the system into applications and data stores, with responsibilities and communications.
- Mermaid C4 syntax provides the diagram notation used in these fenced blocks.
The Canvas-specific reference was not supplied; these views use the official C4 and Mermaid documentation. Validate the Wiki's Mermaid rendering after publication because its renderer version is managed by GitHub.