Application File Structure

Relevant source files

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

• README.md
• todo.md
• MOBILE_BUILD.md
• drizzle/schema.ts
• server/services/pdfExport.ts

The Driveway Estimator Pro (easy-asphalt) project is organized as a monorepo-style full-stack application. It integrates a React-based frontend, a Node.js Express backend, and mobile native projects managed through Capacitor. The architecture is designed for cross-platform deployment, supporting web, iOS, and Android from a single codebase.

High-Level Project Architecture

The application is split into three primary layers: the frontend client, the backend server, and the database layer managed by Drizzle ORM. Communication between the client and server is handled via tRPC for end-to-end type safety.

System Data Flow

The following diagram illustrates the relationship between the major directory structures and how data flows through the system.

The diagram shows the user interacting with pages, which communicate via tRPC to the server's routers and services, ultimately persisting data in the schema defined in the Drizzle directory. Sources: README.md:104-124, MOBILE_BUILD.md:21-30

Root Directory Structure

The root directory contains configuration files for the development environment, build tools, and the entry points for the native mobile wrappers.

File/Directory	Description
client/	React web application source code.
server/	Express backend with tRPC procedures and business logic.
drizzle/	Database schema definitions and migration files.
ios/	Native Xcode project for iOS deployment.
android/	Native Gradle project for Android deployment.
capacitor.config.ts	Configuration for the Capacitor native bridge.
package.json	Project dependencies and mobile build scripts.

Sources: README.md:104-124, MOBILE_BUILD.md:21-30

Frontend Structure (client/)

The client directory contains the React 19 application. It follows a modular structure where pages and reusable UI components are separated.

Directory Breakdown

• src/pages/: Contains the primary view components such as Home.tsx, ProjectDetail.tsx, and SharedProject.tsx.
• src/components/: Houses reusable UI elements, including standard Shadcn/UI components (found in ui/) and specialized components like AIChatBox.
• src/lib/: Contains utility functions and the tRPC client configuration.
• src/_core/: Contains framework-level code, such as authentication hooks (useAuth.ts).

Sources: README.md:104-113, client/src/pages/ProjectDetail.tsx:1-20

Backend Structure (server/)

The server is built using Express.js and tRPC. It is divided into routers (API endpoints) and services (internal business logic).

Core Components

• routers/: Defines the tRPC procedures for projects, authentication, and pricing.
• services/: Contains the heavy lifting logic, including:
  • Edge Detection: AI vision analysis for driveway boundaries.
  • Pricing Service: Logic for calculating material costs based on ZIP codes.
  • PDF Export: PDF generation using jsPDF.
• db.ts: Handles database connection and query execution using Drizzle ORM.

Logic Flow for Services

The services layer operates as the bridge between raw database data and the API procedures.

The diagram represents how tRPC routers call specific services like pdfExport.ts to process data from the schema. Sources: README.md:114-120, server/services/pdfExport.ts:7-15

Database Layer (drizzle/)

The database layer is centralized in the drizzle/ directory. It uses Drizzle ORM to provide type-safe interactions with a MySQL/TiDB database.

Schema Definitions (schema.ts)

The project defines four primary tables:

1. users: Stores authentication identifiers (openId) and user roles.
2. projects: The central table storing driveway measurements, S3 photo URLs, AI-calculated square footage, and material selections.
3. projectShares: Manages unique tokens for contractor access.
4. materialPrices: Caches regional pricing data.

Sources: drizzle/schema.ts:13-100, todo.md:5-10

Mobile Native Structure

The application utilizes Capacitor to wrap the web assets into native containers.

• ios/App/App/Info.plist: Manages iOS permissions for Camera and Location.
• android/app/src/main/AndroidManifest.xml: Manages Android permissions.
• capacitor.config.ts: Configures the web directory (typically dist) that Capacitor uses to sync assets to native projects.

Mobile Build Cycle

This flow shows the transition from web code to native mobile binaries. Sources: MOBILE_BUILD.md:32-45, MOBILE_BUILD.md:136-150

Summary

The file structure of easy-asphalt emphasizes clear separation between the UI, business logic, and database schema. By leveraging tRPC and Drizzle ORM, the project maintains a single source of truth for data types across the client/, server/, and drizzle/ directories, while Capacitor allows the client/ code to be deployed natively via the ios/ and android/ directories.

Sources: README.md:104-124, MOBILE_BUILD.md:21-30