View code
Selected source code
Start with the architecture guide, then explore the business rules, server boundaries, storage, and tests behind ReturnBench. These are actual files bundled from the same build you are viewing.
How the app is structured
- Public example
- Shared business rules run in the browser with a locally saved workspace. The view selector does not grant real account permissions.
- Private workspace
- An authenticated Base44 gateway checks the caller, role and work-order access before reading or changing Base44 entities and private files. This host forwards the visitor's session token through a fixed app gateway.
- Service records
- Quality checks and sharing permissions are verified against the current order revision. PDF, CSV and print output are assembled from the authorized payload. Original uploads remain separate.
Only the files listed below are included. Credentials, environment files, private records, and platform configuration are excluded. This page has no file-reading endpoint or editor access.
Architecture guide
docs/ARCHITECTURE.md
Request flow, module responsibilities, access boundaries and the rules that keep repairs and service records consistent.
Read-only source from this build
# ReturnBench architecture
ReturnBench manages equipment repair: intake, assessment, customer-approved
estimates, technician work, quality checks and return. All paths below are
relative to the repository root.
## Execution and access
The public /app workspace uses fictional records in versioned browser storage.
Its role selector is a walkthrough control. This unified demo serves the
interface with TanStack Start on a Cloudflare Worker through Sites hosting.
Private /workspace calls the authenticated Base44 gateway at
/api/returnbench/v1 through a fixed, app-specific server proxy.
Identity, privileged storage and private files remain on Base44.
Social sign-in opens a native Base44 window because the platform rejects
unregistered external OAuth return domains. The native callback sends the
session only to this site's fixed origin. The receiving window checks the
sender origin, popup identity and a short-lived random state, verifies the
session with the app-scoped user endpoint, then installs it. Session tokens
are never put in a public URL or a handoff database. The supplied password
and MFA flows remain intact. Logout clears both origins' stored sessions and
returns through a fixed native landing page.
Private privileges come from an administrator-managed RepairTeamMember record,
not a user-editable profile. Customers see their own orders. Technicians see
assigned orders with contact details withheld. Coordinators manage the queue.
Direct entity access is restricted; the service boundary returns an explicit
viewer-scoped projection.
## Follow a request
WorkspaceContext.jsx chooses the browser or private adapter. In this external
build, remote.js and gateway-client.js send the visitor's token to the fixed
gateway. The Base44 route authenticates it before gateway.js validates the
operation. repository.js resolves the authenticated role, loads the permitted
order and commits the domain result. The original Base44 app continues to use
server-fns.js for its own interface and shares the same business modules.
Important modules under src/lib/returnbench:
- domain.js: state transitions, quote approval, ownership, quality gates,
evidence permissions and safe service-record fields.
- validation.js: bounded request and command shapes; integer money arithmetic.
- repository.js: membership, scoped reads and conditional persistence.
- gateway.js: bounded JSON/multipart contract, operation allowlist and safe errors.
- upload-server.js: validated provider uploads, signed links and fresh report
permission checks.
- storage.js: durable browser saves, damaged-data errors and stale histories.
- exports.js: selected CSV/HTML/PDF fields and authorization before release.
Interface components live in src/components/returnbench. They show valid actions,
but authorization and state checks still run in the domain and server.
## The order is the consistency boundary
Each RepairOrder stores bounded estimates, work logs, quality results, evidence
metadata and history. A command checks the observed revision and writes the next
aggregate with one conditional update. A conflict requires a reload, never a
blind retry. Customer approval names the exact current estimate revision.
Estimates use integer cents and quantities, not floating-point money.
Only an approved estimate and assigned technician allow repair to start. Work
must be recorded before a quality check. Passing requires all three checks;
failing returns the item to repair. Return and service-record generation require
a valid passed check. Completed work cannot silently reopen.
Uploads are a separate provider operation. File headers detect type mismatch;
they are not malware scanning. A failed order commit after upload may leave an
unlinked private blob for administrator cleanup. Original files stay private;
service records select only permitted customer-visible file metadata.
## Failure and export rules
Browser saves preserve unreadable or unsupported data. Revisions and generation
markers reject detectable stale saves; localStorage is not a database transaction
between tabs. The example limits files to 1 MB to fit browser storage; private
uploads allow 10 MB per file, up to three per order.
Remote mutations refresh even after an error because a response can fail after
persistence. If saving succeeds but reloading fails, the interface asks the user
to inspect the saved result before repeating the action.
Service records are rebuilt from current authorized records. After asynchronous
rendering, authorization and revision are checked again before saving. Private
contacts, internal notes and file storage references never enter the report.
Exports list permitted file names; they do not embed original uploads. Previously
downloaded files cannot be recalled.
## Verification and extension
Run npm test, npm run lint and npm run build. Regression tests use fabricated
records and fake storage/providers. Private account, upload and provider
conditional-write workflows still require live verification before delivery.
The external-backend-client.js uses a fixed app ID and API origin with
only the visitor's bearer token. It never accepts platform service credentials
from incoming headers. The original Base44 middleware receives those credentials
from its platform; no service token is exported to this host or the browser.
The host proxy preserves the private gateway's upload limits and permissions.
Browser storage belongs to an origin. All styles on this host share the same
versioned example workspace: a style is presentation, never a separate data
tenant or permission. Previous walkthrough saves on Base44 and the separate
Netlify studies stay on those origins. They are not silently imported or reset.
Private records continue in the same Base44 entities and are not migrated.
## Presentation and the design room
/design-room is the single entry link for reviewers. Relay, Forma and
Standard have equal places in the chooser. Standard keeps the original
product's URL and remains the default at /. Retired style parameters resolve
to Standard on the requested page. An allowlisted style query
parameter is preserved through app navigation and direct refreshes.
src/styles/registry.jsx selects one stylesheet, font set and motion provider;
the shared workspace, validation and storage modules do not depend on style.
Alternate homepage illustrations and the 3D scene are loaded when selected.
Motion preferences respect reduced-motion settings and never mutate records.
First-time visitors start in light mode. The appearance provider stores a
visitor's explicit choice of light or dark under
returnbench-color-mode, independently of repair data. It applies the saved
mode before the page hydrates, including on direct links and sign-in pages.
Forma's InspectionScene.jsx owns the WebGL lifecycle, studio lighting,
viewport framing and on-demand drawing. camera-model.js creates and disposes
the procedural camera's geometry, materials and canvas textures. Rigid hardware
shares draw calls; optical layers retain separate transforms for inspection.
No remote model or texture service is required. The static fallback is rendered
from this same model. Form and workspace behavior stays in the shared modules.
Component close-ups frame only the selected Forma assembly. Separation is a
continuous presentation value; it never changes a repair. Other homepage tours
also use local view state and fabricated sample records, independently of the
saved workspace. Standard's repair chapters and Relay's handoff records
demonstrate the workflow without submitting commands. See docs/INTERACTION_REVIEW.md for the
reference research and implementation boundaries.
The read-only /code page uses an explicit source allowlist and literal build-time
imports. Add a file only after checking it is safe to share. No visitor input may
become a file path. Payments, outgoing email and courier booking are unconfigured.
Our review process
Ready for human reviewWe use AI to assist development. Before client delivery, we require human review of every feature, supported by tests and workflow checks. Our reviews focus on clear code, maintainability and performance.
Automated checks support this process; they do not replace human review. These changes are ready for an engineer’s review.