Skip to content

README.md

Latest commit

 

History

History
146 lines (104 loc) · 2.99 KB

README.md

File metadata and controls

146 lines (104 loc) · 2.99 KB

FieldTrack API

Production backend for FieldTrack workforce operations.

This service is implemented with Fastify + TypeScript, Supabase (Postgres), Redis, and BullMQ workers.

Overview

The API provides multi-tenant endpoints for:

  • authentication and identity (/auth/*)
  • attendance and location tracking
  • expenses and approvals
  • admin dashboards, analytics, and operational tooling
  • webhook and API key management

All tenant data access is scoped by organization_id derived from authenticated identity.

Architecture

Core stack:

  • Fastify 5 + TypeScript (ESM)
  • Supabase Postgres clients (anon + service role)
  • Redis + BullMQ
  • OpenTelemetry + Prometheus metrics
  • Zod validation

Runtime layout:

  • src/routes: route registration and system routes
  • src/modules: domain modules (auth, attendance, expenses, analytics, admin, etc.)
  • src/middleware: auth and role guards
  • src/db: tenant-scoped query helpers
  • src/workers: queue workers and scheduled jobs

Workers started by src/workers/startup.ts:

  • distance worker
  • analytics worker
  • webhook worker
  • snapshot worker

Scheduled jobs:

  • snapshot reconciliation job (reconcile_snapshot_tables() every 5 minutes)
  • retry-intent cleanup job

Key Features

  • JWT and API key auth (Authorization: Bearer ... or X-API-Key)
  • strict role-based authorization (ADMIN, EMPLOYEE)
  • attendance lifecycle (check-in and check-out) with async post-processing
  • location ingest (single + batch)
  • expense lifecycle with admin review and CSV export
  • admin SSE stream at /admin/events
  • queue/system/internal admin observability endpoints

Environment Setup

Environment is validated by src/config/env.ts at startup.

Required baseline variables:

  • APP_ENV
  • PORT
  • SUPABASE_URL
  • SUPABASE_ANON_KEY
  • SUPABASE_SERVICE_ROLE_KEY
  • SUPABASE_JWT_SECRET
  • REDIS_URL
  • API_BASE_URL
  • APP_BASE_URL
  • CORS_ORIGIN

Common optional variables:

  • FRONTEND_BASE_URL
  • METRICS_SCRAPE_TOKEN
  • TEMPO_ENDPOINT
  • WORKERS_ENABLED

Local Run

Prerequisites:

  • Node.js 24+
  • npm
  • Redis
  • Supabase project

Commands:

npm install
npm run dev

Useful scripts:

  • npm run dev
  • npm run build
  • npm start
  • npm run typecheck
  • npm run lint
  • npm test

API Surface

System endpoints:

  • GET /
  • GET /health
  • GET /ready
  • GET /metrics
  • GET /openapi.json
  • GET /docs

Full endpoint contract and examples: docs/API_REFERENCE.md.

Deployment Summary

Production deploy is driven by GitHub Actions and scripts/deploy.sh.

High-level flow:

  1. CodeQL deep scan gate
  2. validate + tests
  3. docker build, vulnerability scan, push to GHCR
  4. VPS readiness check
  5. blue-green deploy
  6. health and smoke checks
  7. rollback on failure

Liveness gate is /health (not /ready).

See docs/DEPLOYMENT.md for detailed CI/CD and rollback behavior.

Documentation

  • docs/API_REFERENCE.md
  • docs/ARCHITECTURE.md
  • docs/DEPLOYMENT.md
  • docs/ROLLBACK_SYSTEM.md
  • docs/env-contract.md
  • docs/infra-contract.md