A3Service

Field service management and intelligent technical library for HVAC and boiler technicians.

A3Service is a comprehensive platform designed for field service technicians, featuring an offline-first mobile application, a robust backend API, and an AI-driven data pipeline. It brings job scheduling, offline synchronization, and an extensive, searchable library of boiler fault codes, technical specs, and maintenance tasks into one unified ecosystem.

React Native (Expo) · NestJS · PostgreSQL · WatermelonDB · Python Data Pipeline (Gemini AI)

What Makes A3Service Different

Most field service applications assume a constant internet connection, but boiler rooms and basements often lack cell service. A3Service uses an offline-first architecture with WatermelonDB, allowing technicians to view jobs, record service logs, and search technical manuals without a connection. Once back online, the app seamlessly resolves conflicts and syncs with the server.

Furthermore, A3Service builds its technical intelligence through an automated Python data pipeline. It discovers, downloads, and processes hundreds of raw PDF boiler manuals using Gemini AI, extracting structured fault codes, safety warnings, and diagnostic steps so technicians have instant, searchable access to manufacturer data.

Product Highlights

Offline-First Mobile Experience

Built with Expo and WatermelonDB, the mobile application stores its data locally. Technicians can view schedules, read manuals, and log labor and parts completely offline. Background sync pushes changes to the server automatically when connectivity is restored.

Intelligent Manual Ingestion

The standalone Python data pipeline discovers manufacturer PDFs across the web and downloads them locally. It then feeds them through Gemini 2.5 Flash to extract a structured JSON representation of fault codes, status codes, and maintenance procedures, creating a rich technical library.

Centralized Job Management

The NestJS backend manages technicians, clients, sites, schedules, and service logs. It features a robust sync engine that handles idempotency and implements conflict resolution policies when mobile clients push conflicting updates.

Monorepo Architecture

The workspace is an Nx monorepo containing the mobile app, backend API, data pipeline, and a shared-schema library that guarantees type safety across the frontend and backend.

Feature Overview

Area	Functionality
Job Management	Schedule jobs, manage priorities, track time, and record consumed parts.
Offline Sync	Local-first WatermelonDB database with server-side conflict resolution policies.
Technical Library	Searchable fault codes, diagnostic steps, and boiler model specifications.
Data Pipeline	Automated PDF downloading, hashing, and Gemini-powered JSON extraction.
User Management	Role-based access for technicians and managers, profile management, and secure JWT sessions.

Tech Stack

Layer	Technology
Mobile App	React Native, Expo (SDK 54), React Navigation, Expo SQLite
Local Database	WatermelonDB, with Observables
Backend API	Node.js, NestJS 11
Database	PostgreSQL, Prisma ORM
AI Data Pipeline	Python, uv package manager, Gemini 2.5 Flash
Shared Types	TypeScript, Zod
Monorepo	Nx Workspace

Architecture

Mobile App (Expo)
    |
    |  WatermelonDB (Offline-first)
    |  Sync payload + JWT
    v
NestJS API (Backend)
    |
    |-- Sync Engine   (conflict resolution, idempotency)
    |-- Services      (jobs, users, libraries)
    |
    +--> PostgreSQL   (users, jobs, service logs, sync conflicts)
            ^
            |  Structured JSON ingestion
Python Data Pipeline
    |
    |-- Downloader    (PDF discovery and download)
    |-- Extractor     (Gemini AI extraction)

Folder Structure

A3Service/
├── apps/
│   ├── api/              # NestJS backend and Prisma schema
│   ├── data-pipeline/    # Python pipeline for manual ingestion
│   └── mobile/           # Expo React Native offline-first app
├── libs/
│   └── shared-schema/    # TypeScript interfaces shared between frontend & backend
├── docs/                 # Documentation and project planning notes
├── package.json          # Root dependencies and workspace scripts
└── nx.json               # Nx monorepo configuration

Running Locally

Prerequisites

• Node.js 22+
• npm 10+
• Python 3.12+ and uv package manager (for data pipeline)
• PostgreSQL
• Expo Go installed on your mobile device

1. Install Workspace Dependencies

npm install

2. Configure and Start the Backend

Make sure PostgreSQL is running, then generate the Prisma client and apply migrations:

npm run prisma:generate
npm run prisma:migrate:dev
npm run prisma:seed

Start the NestJS API:

npx nx build api
node dist/apps/api/main.js

The API will start at http://localhost:3000/api.

3. Start the Mobile App

Start the mobile app using a native build (required for WatermelonDB):

npx nx run:android

(Note: Because WatermelonDB contains custom native code, you must build the app natively rather than using the standard Expo Go client. Nx intentionally sets the Metro projectRoot to the workspace root for SDK 54+ module resolution).

4. Run the Data Pipeline (Optional)

To ingest and extract boiler manuals, navigate to the pipeline directory, set up your .env with a GEMINI_API_KEY, and install dependencies:

cd apps/data-pipeline
uv sync

Discover and download manuals for a specific brand:

uv run python download_manuals.py discover --brand Bosch
uv run python download_manuals.py download --brand Bosch --limit 5

Process the downloaded PDFs with Gemini:

uv run python run_pipeline.py --brand Bosch

Testing

Run tests across the monorepo using Nx:

npx nx test api
npx nx test mobile

Engineering Notes

• Offline-First: The mobile app relies heavily on WatermelonDB for its reactive, offline-first data model. The UI responds instantly to local changes.
• Sync Conflicts: Database sync conflicts are managed server-side, using SyncLog and SyncConflict records with configurable resolution policies (SERVER_WINS, CLIENT_WINS, MANUAL_REVIEW).
• Decoupled Pipeline: The Python data pipeline is deliberately decoupled from the API. It focuses purely on the ETL (Extract, Transform, Load) workflow, outputting structured JSON to a local output_json/ directory for manual review or eventual database ingestion.
• Security: Passwords are hashed using bcrypt, and API routes are secured with JWT-based refresh sessions.