Documentation

Frontend Architecture

The PatrolLink frontend consists of two distinct surfaces: the mobile app for guards and server-rendered web views for documentation and authentication.

Mobile App (React Native + Expo)

The guard-facing mobile application is built with React Native using the Expo managed workflow. This provides cross-platform compatibility (iOS and Android) with access to native device features:

• expo-location — GPS tracking for patrol routes and location check-ins
• expo-camera — Photo capture for incident reports and checkpoint evidence
• expo-notifications — Push notification support for real-time alerts
• expo-secure-store — Secure token storage for JWT authentication
• React Context API — State management for user sessions and patrol state

The app uses Expo Router for file-based navigation and communicates with the backend via fetch() calls to the Express.js API.

Web Views (EJS)

Documentation, authentication (login/signup), pricing, and the admin dashboard are server-rendered using EJS templates. This approach avoids the complexity of a separate frontend framework for pages that are primarily content or form-based. Templates are served directly by the Express server with inline CSS and minimal client-side JavaScript.

Express.js Server

The backend is built on Express.js 5 and serves as the central API gateway. It handles authentication, session management, routing, rate limiting, and communication with the database and Directus CMS.

Server Configuration

• Express 5 with middleware pipeline: helmet, cors, cookie-parser, body-parser, express-session
• View engine: EJS for server-rendered pages
• PostgreSQL connection via pg library for sessions and direct queries
• Directus REST API integration for user and content management
• Rate limiting on auth endpoints to prevent brute-force attacks

Authentication & Authorization

PatrolLink uses a dual authentication system:

• JWT tokens — Primary auth mechanism for mobile app API calls. Tokens are generated on login, include user role and organization data, and are verified on protected routes via the verifyTokenMiddleware.
• Express sessions — Used for web views (admin dashboard). Login creates a session with user data and a JWT token for server-to-API calls.
• Role-based access — The requireRole() middleware restricts endpoints to specific roles (admin, supervisor).

Auth APIs

All API responses follow the format { "message": "...", "data": ... } for success or { "error": "...", "message": "..." } for errors.

// Example response (201 Created)
{
  "message": "User registered successfully",
  "user": { "id": "abc123", "name": "John Doe", "phone": "+254712345678", "role": "guard" }
}

// Example response (200 OK)
{
  "message": "Login successful",
  "user": { "id": "abc123", "role": "admin" },
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "returnTo": "/admin/dashboard"
}

{ "message": "Logout successful" }

{ "valid": true, "user": { "id": "abc123", "role": "guard" } }

Guard APIs

Endpoints used by the mobile app for assignments, patrol lifecycle, location tracking, and logs.

{ "assignments": [ { "id": "asg1", "location": "loc1", "assigned_areas": "Gate A", "start_time": "09:00", "end_time": "17:00" } ] }

Admin APIs

Endpoints for the admin dashboard to manage guards, assignments, locations, patrols, and logs. All scoped to the authenticated admin's organization via invite_code.

{ "message": "Guard removed successfully", "deleted": { "assignments": 2, "logs": 8, "patrols": 5 } }

Additional APIs

{ "valid": true, "message": "Invite code is valid" }

Middleware

Error Handling

All error responses follow a consistent format:

{ "error": "ErrorType", "message": "Human-readable description" }

Database — PostgreSQL

PatrolLink uses PostgreSQL as its primary database for storing sessions and executing direct queries. User and content data is managed through Directus, which also uses PostgreSQL as its backing store.

Schema Overview

The database schema is managed by Directus and includes custom collections for PatrolLink-specific data. The pg library is used for direct PostgreSQL queries, primarily for session storage and admin dashboard queries.

Key Tables / Collections

CMS — Directus

Directus serves as the headless CMS layer, providing auto-generated REST APIs for CRUD operations on all data collections. It eliminates the need to build custom admin interfaces for data management while offering a powerful SDK for programmatic access.

Configuration

• Directus is configured via DIRECTUS_URL and DIRECTUS_TOKEN environment variables
• The server uses Directus's REST API for querying users, creating records, and managing content
• A custom query() function wraps Directus API calls with consistent error handling
• Directus provides the admin UI for manually managing users, content, and schema changes

Environment Variables

Create a .env file in the backend root with the following:

# Server
APIPORT=5000
NODE_ENV=development

# JWT Secret (change in production)
JWT_SECRET=your-super-secret-jwt-key

# Directus Configuration
DIRECTUS_URL=http://your-directus-instance.com
DIRECTUS_TOKEN=your-directus-static-token

# PostgreSQL
DB_USER=postgres
DB_HOST=localhost
DB_NAME=omniwatch
DB_PASSWORD=your-password
DB_PORT=5432
DB_SSL=false

# CORS Allowed Origins (optional, comma-separated)
CORS_ALLOWED_ORIGINS=http://localhost:5000,http://localhost:8081

Running the App

# Install dependencies
npm install

# Development mode with auto-reload
npm run dev

# Production mode with PM2
npm run prod

# Or start directly
npm start