# asanth7/distributegpu architecture

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

- Interactive diagram: https://gitdiagram.com/asanth7/distributegpu
- Repository: https://github.com/asanth7/distributegpu

## Overview

1. **Project shape**
   - This is a **Next.js App Router** codebase that combines a browser UI, server-side API routes, and a rendering pipeline.
   - The architecture is not just a static site: it has a **task/job backend**, **database access**, and likely **object storage integration** for uploaded assets.

2. **Primary user-facing surfaces**
   - `app/page.tsx` is the main entry point.
   - `app/design/page.tsx` and `app/job/page.tsx` are the two specialized UI areas, suggesting separate flows for **creating/designing work** and **viewing or processing jobs**.
   - `app/components/*` contains the UI and rendering primitives used by those pages.

3. **Client-side rendering subsystem**
   - `ModelViewer.tsx`, `RayTrace.tsx`, and `WorkerRenderer.ts` indicate a substantial **in-browser 3D rendering** subsystem.
   - The `shaders/` tree contains scene, camera, material, BVH, and raytracer-related code, which points to a **GPU/WebGPU-style ray tracing pipeline** rather than a normal DOM-only app.
   - This subsystem is likely responsible for previewing scenes or generated output directly in the browser.

4. **Upload and asset ingestion path**
   - `MosaicUpload.tsx` and the `app/api/upload-url/route.ts` endpoint form the upload flow.
   - The presence of `scripts/configure-s3-cors.ts` strongly suggests **Amazon S3** or similar object storage is used for asset uploads, probably via **pre-signed upload URLs** returned by the API.
   - This keeps large scene/image assets out of the Next.js server and moves them directly from browser to storage.

5. **Task creation and orchestration**
   - `app/api/create-task/route.ts` is the entry point for creating a new render/process task.
   - `TaskPreview.tsx` likely shows the created task or its associated asset before submission or while it is running.
   - The app appears to convert uploaded content into a tracked task that later becomes one or more executable jobs.

6. **Job queue / worker lifecycle**
   - The `app/api/jobs/*` routes define a small job-management API:
     - `next` for claiming the next available job,
     - `start` for marking work as started,
     - `complete` for finishing a job,
     - `all` for listing jobs.
   - This is a classic **queue-like workflow** with explicit worker state transitions, suitable for one or more external workers polling the backend.

7. **Database boundary**
   - `db/schema.sql` defines the persistence model, and `lib/db.ts` centralizes DB access.
   - `app/api/setup-db/route.ts` suggests the schema can be initialized from the app itself, which is useful for local setup or deployment bootstrap.
   - The DB appears to be the source of truth for tasks, jobs, and their state transitions.

8. **External service validation**
   - `app/api/test-db/route.ts` and `app/api/test-aws/route.ts` are diagnostic endpoints for checking infrastructure connectivity.
   - These routes imply the app depends on at least two external services: a **SQL database** and **cloud storage / AWS-related infrastructure**.

9. **Scene/test assets and rendering validation**
   - `public/raytraced-scene.mtl`, `test_scene.txt`, and `verified_scene.txt` indicate this repo includes sample scene data and a verified reference result.
   - That points to a workflow where rendered output or parsed scene content is compared against expected results, likely for validation of the ray tracing pipeline.

10. **Scripts and operational tooling**
   - `scripts/test-task-creation.js` is a manual or automated smoke test for the task pipeline.
   - `scripts/configure-s3-cors.ts` is operational setup for browser-to-storage uploads.
   - These scripts are part of the repo’s deployment and integration story, not just development convenience.

11. **Important architectural boundary**
   - The repo cleanly separates:
     - **Browser rendering/UI** in components and shaders,
     - **Task/job orchestration** in API routes,
     - **Persistence** in the SQL database,
     - **Binary/large asset handling** in object storage.
   - That separation is the key thing to capture in an architecture diagram.

12. **Likely runtime model**
   - The Next.js app serves both pages and API routes in the same deployment.
   - Browser clients interact with the API to create tasks and fetch upload URLs.
   - Workers or processing clients interact with the job endpoints to claim and complete work.
   - The rendering components can operate locally in the browser, while job state and assets are coordinated server-side.

Main entry points: [`app/components`](https://github.com/asanth7/distributegpu/tree/main/app/components) (UI components), [`lib/db.ts`](https://github.com/asanth7/distributegpu/blob/main/lib/db.ts) (DB access), [`app/api/create-task/route.ts`](https://github.com/asanth7/distributegpu/blob/main/app/api/create-task/route.ts) (Create task), [`shaders`](https://github.com/asanth7/distributegpu/tree/main/shaders) (Shaders)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Browser app"]
  node_node_home["Home<br/>page<br/>[page.tsx]"]
  node_node_design["Design<br/>page<br/>[page.tsx]"]
  node_node_job["Job<br/>page<br/>[page.tsx]"]
  node_node_components["UI components<br/>client components"]
  node_node_mosaicupload["Upload UI<br/>upload flow<br/>[MosaicUpload.tsx]"]
  node_node_taskpreview["Task preview<br/>task UI<br/>[TaskPreview.tsx]"]
end

subgraph group_group_api["Server API"]
  node_node_api_upload["Upload URL<br/>api route<br/>[route.ts]"]
  node_node_api_create_task["Create task<br/>api route<br/>[route.ts]"]
  node_node_api_jobs["Jobs API<br/>job queue api"]
  node_node_api_setupdb["Setup DB<br/>bootstrap route<br/>[route.ts]"]
  node_node_api_diagnostics["Diagnostics<br/>health routes<br/>[route.ts]"]
end

subgraph group_group_render["Rendering pipeline"]
  node_node_modelviewer["Model viewer<br/>[ModelViewer.tsx]"]
  node_node_raytrace["Ray trace UI<br/>renderer<br/>[RayTrace.tsx]"]
  node_node_worker_renderer["Worker renderer<br/>worker bridge<br/>[WorkerRenderer.ts]"]
  node_node_shaders["Shaders<br/>GPU pipeline"]
end

subgraph group_group_data["Persistence and assets"]
  node_node_db_schema[("DB schema<br/>sql schema<br/>[schema.sql]")]
  node_node_lib_db["DB access<br/>database client<br/>[db.ts]"]
end

subgraph group_group_ops["Ops and validation"]
  node_node_s3_cors["S3 CORS<br/>ops script"]
  node_node_test_task["Task smoke test<br/>script"]
  node_node_scene_asset["Scene asset<br/>sample mtl"]
  node_node_test_scene["Test scene<br/>fixture<br/>[test_scene.txt]"]
  node_node_verified_scene["Verified scene<br/>reference<br/>[verified_scene.txt]"]
end

node_node_home -->|"uses"| node_node_components
node_node_design -->|"uses"| node_node_components
node_node_job -->|"uses"| node_node_components
node_node_components -->|"includes"| node_node_modelviewer
node_node_components -->|"includes"| node_node_mosaicupload
node_node_components -->|"includes"| node_node_taskpreview
node_node_components -->|"includes"| node_node_raytrace
node_node_raytrace -->|"delegates"| node_node_worker_renderer
node_node_worker_renderer -->|"executes"| node_node_shaders
node_node_modelviewer -->|"renders with"| node_node_shaders
node_node_mosaicupload -->|"requests"| node_node_api_upload
node_node_taskpreview -->|"submits"| node_node_api_create_task
node_node_api_create_task -->|"persists"| node_node_lib_db
node_node_api_jobs -->|"reads/writes"| node_node_lib_db
node_node_api_upload -->|"depends on"| node_node_s3_cors
node_node_api_setupdb -->|"initializes"| node_node_db_schema
node_node_lib_db -->|"maps to"| node_node_db_schema
node_node_api_diagnostics -->|"checks"| node_node_lib_db
node_node_api_diagnostics -->|"checks"| node_node_s3_cors
node_node_test_task -->|"smokes"| node_node_api_create_task
node_node_test_scene -.->|"compares"| node_node_verified_scene
node_node_scene_asset -.->|"validates"| node_node_shaders

click node_node_home "https://github.com/asanth7/distributegpu/blob/main/app/page.tsx"
click node_node_design "https://github.com/asanth7/distributegpu/blob/main/app/design/page.tsx"
click node_node_job "https://github.com/asanth7/distributegpu/blob/main/app/job/page.tsx"
click node_node_components "https://github.com/asanth7/distributegpu/tree/main/app/components"
click node_node_modelviewer "https://github.com/asanth7/distributegpu/blob/main/app/components/ModelViewer.tsx"
click node_node_mosaicupload "https://github.com/asanth7/distributegpu/blob/main/app/components/MosaicUpload.tsx"
click node_node_taskpreview "https://github.com/asanth7/distributegpu/blob/main/app/components/TaskPreview.tsx"
click node_node_raytrace "https://github.com/asanth7/distributegpu/blob/main/app/components/RayTrace.tsx"
click node_node_worker_renderer "https://github.com/asanth7/distributegpu/blob/main/app/components/WorkerRenderer.ts"
click node_node_shaders "https://github.com/asanth7/distributegpu/tree/main/shaders"
click node_node_api_upload "https://github.com/asanth7/distributegpu/blob/main/app/api/upload-url/route.ts"
click node_node_api_create_task "https://github.com/asanth7/distributegpu/blob/main/app/api/create-task/route.ts"
click node_node_api_jobs "https://github.com/asanth7/distributegpu/tree/main/app/api/jobs"
click node_node_api_setupdb "https://github.com/asanth7/distributegpu/blob/main/app/api/setup-db/route.ts"
click node_node_api_diagnostics "https://github.com/asanth7/distributegpu/blob/main/app/api/test-db/route.ts"
click node_node_db_schema "https://github.com/asanth7/distributegpu/blob/main/db/schema.sql"
click node_node_lib_db "https://github.com/asanth7/distributegpu/blob/main/lib/db.ts"
click node_node_s3_cors "https://github.com/asanth7/distributegpu/blob/main/scripts/configure-s3-cors.ts"
click node_node_test_task "https://github.com/asanth7/distributegpu/blob/main/scripts/test-task-creation.js"
click node_node_scene_asset "https://github.com/asanth7/distributegpu/blob/main/public/raytraced-scene.mtl"
click node_node_test_scene "https://github.com/asanth7/distributegpu/blob/main/test_scene.txt"
click node_node_verified_scene "https://github.com/asanth7/distributegpu/blob/main/verified_scene.txt"

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_node_home,node_node_design,node_node_job,node_node_components,node_node_mosaicupload,node_node_taskpreview toneBlue
class node_node_api_upload,node_node_api_create_task,node_node_api_jobs,node_node_api_setupdb,node_node_api_diagnostics toneAmber
class node_node_modelviewer,node_node_raytrace,node_node_worker_renderer,node_node_shaders toneMint
class node_node_db_schema,node_node_lib_db toneRose
class node_node_s3_cors,node_node_test_task,node_node_scene_asset,node_node_test_scene,node_node_verified_scene toneIndigo
```

## Components

### Browser app

Next.js pages and client-side UI surfaces.

- [Home](https://github.com/asanth7/distributegpu/blob/main/app/page.tsx): page · Main entry page for the app. · `app/page.tsx`
- [Design](https://github.com/asanth7/distributegpu/blob/main/app/design/page.tsx): page · Design/work creation flow. · `app/design/page.tsx`
- [Job](https://github.com/asanth7/distributegpu/blob/main/app/job/page.tsx): page · Job viewing and processing flow. · `app/job/page.tsx`
- [UI components](https://github.com/asanth7/distributegpu/tree/main/app/components): client components · Shared UI and interaction components. · `app/components`
- [Upload UI](https://github.com/asanth7/distributegpu/blob/main/app/components/MosaicUpload.tsx): upload flow · Browser upload entry for scene/assets. · `app/components/MosaicUpload.tsx`
- [Task preview](https://github.com/asanth7/distributegpu/blob/main/app/components/TaskPreview.tsx): task UI · Displays task state or submitted work preview. · `app/components/TaskPreview.tsx`

### Server API

Route handlers for tasks, jobs, uploads, and diagnostics.

- [Upload URL](https://github.com/asanth7/distributegpu/blob/main/app/api/upload-url/route.ts): api route · Issues pre-signed upload URLs. · `app/api/upload-url/route.ts`
- [Create task](https://github.com/asanth7/distributegpu/blob/main/app/api/create-task/route.ts): api route · Creates a task from submitted assets or scene input. · `app/api/create-task/route.ts`
- [Jobs API](https://github.com/asanth7/distributegpu/tree/main/app/api/jobs): job queue api · Queue-like job lifecycle endpoints. · `app/api/jobs`
- [Setup DB](https://github.com/asanth7/distributegpu/blob/main/app/api/setup-db/route.ts): bootstrap route · Initializes database schema from the app. · `app/api/setup-db/route.ts`
- [Diagnostics](https://github.com/asanth7/distributegpu/blob/main/app/api/test-db/route.ts): health routes · Connectivity checks for database and AWS services. · `app/api/test-db/route.ts`

### Rendering pipeline

Client-side model viewing and ray tracing implementation.

- [Model viewer](https://github.com/asanth7/distributegpu/blob/main/app/components/ModelViewer.tsx): viewer · Interactive 3D scene/model preview. · `app/components/ModelViewer.tsx`
- [Ray trace UI](https://github.com/asanth7/distributegpu/blob/main/app/components/RayTrace.tsx): renderer · Browser-facing ray tracing component. · `app/components/RayTrace.tsx`
- [Worker renderer](https://github.com/asanth7/distributegpu/blob/main/app/components/WorkerRenderer.ts): worker bridge · Worker-side rendering execution bridge. · `app/components/WorkerRenderer.ts`
- [Shaders](https://github.com/asanth7/distributegpu/tree/main/shaders): GPU pipeline · Scene, camera, material, BVH, and raytracer shader modules. · `shaders`

### Persistence and assets

Database schema/access and large asset handling.

- [DB schema](https://github.com/asanth7/distributegpu/blob/main/db/schema.sql): sql schema · Persistence model for tasks, jobs, and state. · `db/schema.sql`
- [DB access](https://github.com/asanth7/distributegpu/blob/main/lib/db.ts): database client · Centralized database access layer. · `lib/db.ts`

### Ops and validation

Setup and smoke-test tooling plus sample scene assets.

- [S3 CORS](https://github.com/asanth7/distributegpu/blob/main/scripts/configure-s3-cors.ts): ops script · Configures browser upload access to object storage. · `scripts/configure-s3-cors.ts`
- [Task smoke test](https://github.com/asanth7/distributegpu/blob/main/scripts/test-task-creation.js): script · Manual or automated task-creation smoke test. · `scripts/test-task-creation.js`
- [Scene asset](https://github.com/asanth7/distributegpu/blob/main/public/raytraced-scene.mtl): sample mtl · Reference scene/material asset for rendering validation. · `public/raytraced-scene.mtl`
- [Test scene](https://github.com/asanth7/distributegpu/blob/main/test_scene.txt): fixture · Sample scene input used for validation. · `test_scene.txt`
- [Verified scene](https://github.com/asanth7/distributegpu/blob/main/verified_scene.txt): reference · Known-good output or reference scene result. · `verified_scene.txt`

## Connections

- Home → UI components: uses · Home page composes shared UI.
- Design → UI components: uses · Design page composes shared UI.
- Job → UI components: uses · Job page composes shared UI.
- UI components → Model viewer: includes · Shared UI includes the model viewer.
- UI components → Upload UI: includes · Shared UI includes upload interaction.
- UI components → Task preview: includes · Shared UI includes task status preview.
- UI components → Ray trace UI: includes · Shared UI includes the ray tracing surface.
- Ray trace UI → Worker renderer: delegates · Ray tracing UI hands work to worker rendering.
- Worker renderer → Shaders: executes · Worker renderer relies on shader pipeline.
- Model viewer → Shaders: renders with · Model viewer uses the GPU/rendering pipeline.
- Upload UI → Upload URL: requests · Browser asks for an upload URL.
- Task preview → Create task: submits · Task preview flow creates a backend task.
- Create task → DB access: persists · Task creation writes to the database.
- Jobs API → DB access: reads/writes · Job lifecycle endpoints update queue state.
- Upload URL → S3 CORS: depends on · Upload flow assumes storage CORS is configured.
- Setup DB → DB schema: initializes · Setup route applies the schema.
- DB access → DB schema: maps to · DB access layer is shaped by the schema.
- Diagnostics → DB access: checks · Database diagnostic route validates connectivity.
- Diagnostics → S3 CORS: checks · AWS diagnostic route validates storage integration.
- Task smoke test → Create task: smokes · Script exercises task creation flow.
- Test scene → Verified scene: compares · Scene fixture is validated against reference output.
- Scene asset → Shaders: validates · Sample asset supports rendering pipeline verification.
