← Back to overview
Trace spoke · architecture

PCB Validator architecture

Hub and spoke boundaries, request paths, and the data flows that matter. Trace keeps the order and the original package. The spoke keeps derived geometry and validation history.

Reading the diagram: solid lines are requests or data, the dashed blue line is a revision upload. Numbered labels match the flow list below. The dashed boundary is the spoke; everything inside it is owned by the validator.
PCB VALIDATOR SPOKE own API, jobs, database and derived artifacts TRACE HUB identity · orders · checkout
Browser
Preact / TypeScript
  • Board rendering and layers
  • Finding navigation
  • Revision upload
displays completed results
Spoke API
FastAPI · Cloud Run
  • Order context and manifest
  • Run lifecycle, findings, revisions
  • Assigned profile from Trace
  • Serves geometry and SSE
Validation worker
Python · Cloud Run Job
  • Fetch files with authorized Hub access
  • Parse Gerber and Excellon
  • Normalize geometry
  • Run spoke-owned DFM rules
5 parse → normalize → validate
Postgres
Spoke database
  • Run state and revisions
  • Findings
Object storage
Derived artifacts
  • Normalized geometry
  • Larger validation artifacts
Trace Hub API
Order and checkout owner
  • Order context and manifest
  • Original files and revisions
  • Assigned manufacturing profile
  • Findings and order-item endpoints
originals stay here
1 order context 2 context, manifest + profile 3 dispatch job 4 fetch files 6 write geometry 7 results findings 8 persist run state 9 read geometry 10 progress completion 11 results geometry 12 upload revision 13 findings + items
Trace-owned Spoke-owned Browser Data flow Revision upload Original files stay in Trace. Derived geometry stays in the spoke.

Components and responsibilities

6 parts
ComponentResponsibility
BrowserPreact / TypeScript
Board rendering, layer controls, finding navigation, revision upload
Spoke APIFastAPI
Order context and manifest, run lifecycle, findings, revision management, Hub integration, geometry serving. Retrieves the assigned profile from Trace and applies the spoke-owned DFM ruleset.
Validation workerPython
Fetch package files with authorized Hub access, parse Gerber and Excellon, normalize geometry, run spoke-owned DFM rules
DatabasePostgres
Revisions, validation runs, findings, processing state
Object storageDerived geometry and larger validation artifacts. The API reads it when serving the browser.
Trace Hub APIOrder context, original package files and revisions, assigned manufacturing profile, findings and order-item endpoints

Main flows

13 steps
  1. Browser requests order context from the spoke.
  2. Spoke retrieves order context, the package manifest, and the assigned manufacturing profile from Trace.
  3. Spoke dispatches a validation job with order ID, revision ID, and file references.
  4. Worker fetches the actual package files from Trace using its own authorized Hub API access.
  5. Worker parses, normalizes and validates the package.
  6. Worker writes derived geometry to object storage.
  7. Worker reports result metadata and findings to the API.
  8. API persists run state and findings in Postgres.
  9. API reads derived geometry from object storage when serving the browser.
  10. API streams validation progress and completion to the browser over SSE.
  11. API returns results and the geometry reference or payload to the browser, which displays the completed results.
  12. Browser uploads a revised package to Trace. The customer triggers validation again from the spoke UI; the spoke reads the new revision through the Hub API and starts a new run.
  13. After the run is persisted, the spoke posts findings and priceable order items to Trace. If Trace is unavailable, this post can be retried without rerunning validation.
Ownership in one line: Trace owns identity, the order, the original package files and revisions, the assigned manufacturing profile, cost roll-up and checkout. The spoke owns interpretation, normalized geometry, runs, DFM rules and derived artifacts, and applies its own ruleset to the assigned profile. Revision upload goes to Trace; the customer triggers validation again from the spoke UI, and the spoke reads the new revision through the Hub API. Findings and items are posted only after the run is persisted, so a failed post can be retried without rerunning validation. The worker fetches files with its own authorized Hub API access and never talks to the database directly; it reports metadata and findings to the API, which persists run state.

The diagram is a design proposal, not a deployment snapshot. The browser never parses Gerber; it renders normalized geometry returned by the spoke.