How asanth7/distributegpu works
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: components UI components · db.ts DB access · route.ts Create task · shaders Shaders
Components 22
Browser app
Next.js pages and client-side UI surfaces.
- Home · Main entry page for the app.
app/page.tsx - Design · Design/work creation flow.
app/design/page.tsx - Job · Job viewing and processing flow.
app/job/page.tsx - UI components · Shared UI and interaction components.
app/components - Upload UI · Browser upload entry for scene/assets.
app/components/MosaicUpload.tsx - Task preview · Displays task state or submitted work preview.
app/components/TaskPreview.tsx
Server API
Route handlers for tasks, jobs, uploads, and diagnostics.
- Upload URL · Issues pre-signed upload URLs.
app/api/upload-url/route.ts - Create task · Creates a task from submitted assets or scene input.
app/api/create-task/route.ts - Jobs API · Queue-like job lifecycle endpoints.
app/api/jobs - Setup DB · Initializes database schema from the app.
app/api/setup-db/route.ts - Diagnostics · 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 · Interactive 3D scene/model preview.
app/components/ModelViewer.tsx - Ray trace UI · Browser-facing ray tracing component.
app/components/RayTrace.tsx - Worker renderer · Worker-side rendering execution bridge.
app/components/WorkerRenderer.ts - Shaders · Scene, camera, material, BVH, and raytracer shader modules.
shaders
Persistence and assets
Database schema/access and large asset handling.
Ops and validation
Setup and smoke-test tooling plus sample scene assets.
- S3 CORS · Configures browser upload access to object storage.
scripts/configure-s3-cors.ts - Task smoke test · Manual or automated task-creation smoke test.
scripts/test-task-creation.js - Scene asset · Reference scene/material asset for rendering validation.
public/raytraced-scene.mtl - Test scene · Sample scene input used for validation.
test_scene.txt - Verified scene · Known-good output or reference scene result.
verified_scene.txt
Connections 22
- 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.