tRPC API Design

Relevant source files

The following files were used as context for generating this wiki page:

• server/_core/trpc.ts
• server/routers/projects.ts
• server/routers/projects.test.ts
• drizzle/schema.ts
• README.md
• todo.md

The tRPC API design in the Driveway Estimator Pro project facilitates end-to-end type safety between the Express.js backend and the React frontend. It centralizes business logic within strongly-typed procedures, handling everything from project management to complex AI-driven driveway edge detection and real-time material pricing lookup.

The API is structured around a core router that delegates specific domain logic to sub-routers, primarily the projectsRouter. It utilizes middleware for authentication and authorization, ensuring that user data is protected and that administrative functions are restricted to authorized accounts.

Sources: README.md:32-44, server/_core/trpc.ts:1-35

Core tRPC Infrastructure

The infrastructure layer defines the foundation for all API procedures, including the creation of the tRPC instance and the definition of reusable middleware for security.

Base Configuration

The tRPC instance is initialized using superjson as a transformer to handle complex data types like Dates and BigInts across the network boundary.
Sources: server/_core/trpc.ts:6-9

Middleware and Procedures

Three primary levels of procedure access are defined:

Procedure Type	Middleware	Access Level
publicProcedure	None	Open to all users (e.g., viewing shared projects)
protectedProcedure	requireUser	Requires valid session context (ctx.user)
adminProcedure	requireUser + role check	Requires user role to be "admin"

Sources: server/_core/trpc.ts:11-41

The diagram shows the authorization flow within the tRPC middleware layer.
Sources: server/_core/trpc.ts:14-41

Projects Router Design

The projectsRouter is the primary functional module, providing endpoints for the full lifecycle of a driveway estimation project.

Project Management Procedures

The router implements standard CRUD operations and specialized business logic:

• list: Retrieves all projects associated with the authenticated user ID.
• getById: Fetches a specific project, verifying ownership before returning data.
• create: Persists a new project including measurements, material choices, and cost estimates.
• delete: Removes project records after verifying ownership.

Sources: server/routers/projects.ts:31-59, server/routers/projects.ts:241-267

AI and Utility Procedures

These procedures integrate external services (LLM vision, storage, pricing) into the type-safe API:

Endpoint	Input Type	Functionality
uploadPhotoAndDetectEdges	Base64 Image, Dimensions	Uploads to S3 and triggers LLM edge detection
getPricing	ZIP, Material, Dimensions	Calculates tons needed and fetches regional pricing
generateMaterialPreview	Photo URL, Material	Triggers AI image generation for visualization
downloadPDF	Project ID	Generates and returns a base64 encoded PDF

Sources: server/routers/projects.ts:64-164, server/routers/projects.ts:315-341

The sequence diagram illustrates the complex flow of the uploadPhotoAndDetectEdges procedure.
Sources: server/routers/projects.ts:64-100

Public Access and Sharing

The API includes a dedicated flow for public sharing, allowing contractors to view estimates without requiring full authentication.

Sharing Flow Implementation

1. Creation: createShareLink generates a unique nanoid(32) token and creates a record in the projectShares table.
2. Notification: If a contractor email is provided, the procedure triggers a sendContractorNotification via the email service.
3. Consumption: getSharedProject uses a publicProcedure to allow retrieval of project details using only the share token.

Sources: server/routers/projects.ts:272-310, drizzle/schema.ts:63-75

Data Structure for Sharing

Field	Type	Description
shareToken	varchar(64)	Unique, unguessable identifier for public access
projectId	int	Reference to the core project record
viewCount	int	Tracks how many times the link was accessed

Sources: drizzle/schema.ts:63-78

Testing Strategy

The tRPC API design is validated through a comprehensive suite of unit and integration tests using vitest.

• Authentication Testing: Verified by creating callers with null context to ensure UNAUTHORIZED errors are thrown.
• Input Validation: Tests confirm that procedures like getPricing handle various material enums (hotmix, millings, etc.) correctly.
• Public Access Validation: Tests ensure getSharedProject is accessible without a user session but still returns NOT_FOUND for invalid tokens.

Sources: server/routers/projects.test.ts:1-120, todo.md:16-17

Conclusion

The tRPC API design for Driveway Estimator Pro ensures a robust, type-safe communication layer. By combining standard CRUD operations with AI-powered services and a secure public sharing mechanism, the API serves as the central coordinator for the application's mobile and web interfaces. Its architecture emphasizes security through middleware while maintaining developer productivity through shared TypeScript types.