Case study 03 / Full-stack application
Repair Desk
From repair request to confirmed handover.
A repair-service application connecting clients, artisans and operators through one accountable booking lifecycle.

- RequestClient
- AssignOperator
- QuoteArtisan
- ApproveClient
- RepairArtisan
- HandoverClient confirms
A service identity carried into the working product.
A four-part repair-joint mark, graphite surfaces and restrained cobalt actions replace the original identity. The home page explains the service journey, while dedicated account layouts and consistent form controls carry that identity into the application.
Client, artisan and operator job cards share a seven-stage progress indicator. Cancelled and disputed bookings show an exception state rather than misleading progress. The redesign preserves server-side ownership checks, quote approval, evidence and handover rules.
The updated interface was reviewed across mobile and desktop sizes. All 64 unit tests and six browser scenarios passed, including the authenticated repair lifecycle and operator workflows.
One job. A shared source of truth.
A repair request involves more than storing a customer and a description. Someone must assign the work, an artisan must propose a price, the client must agree, and completion needs a clear handover. Repair Desk keeps those decisions attached to a booking instead of scattering them across separate conversations.
Client
Creates requests, reviews quotes, uploads permitted evidence, tracks progress and confirms handover.
Artisan
Works on assigned bookings, submits quotes, records evidence and moves approved work toward completion.
Operator
Coordinates the queue, assigns eligible artisans and administers artisan status, service coverage and cities.
The interface asks. The server decides.
Next.js and React provide the interface. Route handlers validate requests with Zod and apply session, role and ownership checks before calling workflow services. Prisma connects those services to PostgreSQL.
Better Auth handles email/password authentication. Authorization adds a separate question: is this actor permitted to perform this action on this booking? An authenticated client cannot approve another client's quote, and an artisan must be assigned and active.
Request boundary
Validate the input and authenticated actor before invoking a domain operation.
Workflow boundary
Check the current state, assignment and expected update timestamp before changing the booking.
Persistence boundary
Commit the booking change, event history and workflow notifications within the transaction.
Make valid transitions explicit.
The primary lifecycle is Requested → Assigned → Quoted → Quote approved → In progress → Awaiting handover → Completed. Rejecting a quote returns the booking to Assigned so the artisan can revise it.
Assignment requires an active artisan with matching city and service coverage. Work can start only after quote approval; finishing work and confirming handover are separate actions. In-app notifications keep relevant participants informed.
Conditional updates compare the displayed booking timestamp and current state. A stale request returns a conflict rather than overwriting a newer decision. The current code also implements cancellation, disputes and operator dispute resolution, with allowed source states and recorded reasons.
Model the relationships behind the workflow.
The PostgreSQL schema separates users, artisan profiles, cities, service categories and bookings. ArtisanCity and ArtisanService model coverage independently of an individual job. Each booking references its client, city, service and optional artisan.
BookingEvent preserves the history behind the current state. BookingEvidence associates a file with its booking and uploader. Notifications belong to individual users, with read state stored separately.
Evidence access is checked against the parent booking. Upload policy constrains file size, file type and lifecycle stage. Small file contents live in PostgreSQL alongside their metadata for this portfolio deployment.
Test the paths that can break trust.
Vitest tests cover workflow rules, validation, authorization and transaction behavior. Playwright includes a real authenticated repair journey, checks for cross-account access, stale quote actions, concurrent requests and evidence access.
GitHub Actions provisions isolated PostgreSQL, applies and checks migrations, runs lint and TypeScript checks, executes unit tests, builds the application and runs Chromium tests. These are implemented checks in the repository; this case study does not claim a current passing run.
The deployment configuration uses a Render web service with an externally configured PostgreSQL connection. Current deployment documentation identifies Neon as the database host. Versioned Prisma migrations initialize the database explicitly; application startup runs the web process. The health endpoint checks database connectivity.
A deliberate boundary around the demo.
Keeping small evidence files in PostgreSQL removes another storage dependency and keeps file access tied to the booking model. The cost is database growth and additional load if file volume increases.
The application has in-app notifications and does not process real payments. It is a portfolio application, without claims of commercial scale or service-level guarantees.
Future: file storage
Move binary payloads to object storage if usage warrants it, retaining metadata and access policy in PostgreSQL.
Future: delivery channels
Add email or push notifications only with retry, delivery-status and failure handling.
Future: operations
Evaluate load behavior and recovery procedures against an explicit deployment target before making reliability claims.
Source reviewed at revision 6e6de84. View the reviewed snapshot.