System Architecture

This page describes the technical architecture of the PaulRentACar CRM — the technology stack, frontend and backend design, multi-tenant model, workflow engine, and data flow patterns.

Architecture Overview

PaulRentACar CRM follows a modern three-tier architecture with clear separation of concerns: a Next.js frontend, a Python FastAPI backend, and a PostgreSQL database. The system is designed for multi-tenant isolation, horizontal scaling, and enterprise-grade security.

High-level architecture — frontend communicates with the backend API, which enforces business rules and persists data to PostgreSQL.

Technology Stack

Frontend Architecture

The frontend is a Next.js 16 application using the App Router, TypeScript, and a feature-based folder structure.

App Router Structure

Component Architecture

Frontend Design Principles

• Server components for static content and data fetching where possible
• Client components for forms, tables, modals, and interactive elements
• Permission-aware rendering — UI elements are hidden based on the user's role permissions
• Central API client — all HTTP calls go through a single configured client with auth headers
• Automatic token refresh — expired access tokens are refreshed transparently
• Responsive layout — works on desktop (1920px) and tablet (768px) with mobile card views

Backend Architecture

The backend follows a layered service pattern with clear boundaries between concerns:

Request → Route → Dependency Injection → Service → Repository → Model → Database

Backend Layer Responsibilities

API Design Pattern

All endpoints follow a consistent REST design with a standard response envelope:

{
  "success": true,
  "data": { ... },
  "message": "Operation completed",
  "errors": []
}

Paginated responses include:

{
  "success": true,
  "data": {
    "items": [],
    "page": 1,
    "page_size": 20,
    "total": 0
  }
}

Route Naming Convention

Multi-Tenant Model

PaulRentACar CRM is multi-tenant by design. Every business entity includes a tenant_id foreign key, ensuring complete data isolation between tenants.

Tenant Isolation Hierarchy

Tenant
  └── Business Unit
        └── Branch
              └── Users (with explicit access grants)
              └── Vehicles, Customers, Contracts, etc.

Access Control Tables

Authorization Flow

Every API request is authorized through this chain:

1. JWT validation — token is valid and not expired
2. Token not revoked — token has not been logged out or blacklisted
3. User exists — the user ID in the token corresponds to an active user
4. Tenant access — the user has access to the tenant_id in the request
5. Branch access — the user has access to the branch_id in the request (where applicable)
6. Permission check — the user has the required permission string (e.g., reservation:create)
7. Record ownership — the requested record belongs to an allowed tenant/branch

Workflow Engine

The platform includes a lightweight, domain-specific workflow engine that manages state transitions, task assignment, approvals, SLA tracking, and audit logging for every major business entity.

Workflow-Managed Entities

Workflow Engine Components

Transition Execution Pattern

Every workflow action follows this sequence:

1. Load the workflow instance for the target entity
2. Verify tenant and branch access for the current user
3. Load the current active workflow version
4. Find the transition matching the current stage and requested action
5. Check the required permission against the user's role
6. Run the validation rule (e.g., "can this contract be checked in?")
7. If approval is required, create an approval request and stop
8. Execute the status update and workflow instance update in one transaction
9. Create a workflow action log entry
10. Create or complete tasks as needed
11. Calculate the next SLA deadline
12. Trigger a notification event
13. Return the updated entity, available actions, and timeline

Workflow API Endpoints

Data Flow Diagram

The following describes the end-to-end data flow for a typical rental transaction:

Customer walks in / books online
        │
        ▼
  ┌─────────────┐
  │   Lead       │  Capture interest, source, assigned agent
  └──────┬──────┘
         │  Convert
         ▼
  ┌─────────────┐
  │   Quote      │  Pricing engine calculates rates, discounts, extras
  └──────┬──────┘
         │  Accept
         ▼
  ┌─────────────┐
  │ Reservation  │  Vehicle held, confirmation sent, SLA starts
  └──────┬──────┘
         │  Checkout
         ▼
  ┌─────────────┐
  │   Contract   │  Vehicle condition recorded, mileage, fuel, signature
  └──────┬──────┘
         │  Active rental period
         ▼
  ┌─────────────┐
  │  Check-in    │  Return inspection, damage assessment, final mileage
  └──────┬──────┘
         │  Billing
         ▼
  ┌─────────────┐
  │   Invoice    │  Line items: rental, extras, fines, damage, Salik
  └──────┬──────┘
         │  Payment
         ▼
  ┌─────────────┐
  │   Payment    │  Allocation across invoices, deposit release
  └──────┬──────┘
         │  Accounting
         ▼
  ┌─────────────────────┐
  │ Accounting Subledger │  Journal entries, posting batches, export to ERP
  └─────────────────────┘

Each step in this flow is managed by the workflow engine, creating audit log entries and SLA tracking at every transition.

Accounting Subledger

The platform includes a summary journal posting subledger that feeds the tenant's existing accounting/ERP system. This is not a full general ledger — it is an operational subledger that generates balanced journal entries and exports them in CSV, Excel, JSON, or API format.

Accounting Data Flow

Operational Transaction (invoice, payment, deposit, fine, etc.)
        │
        ▼
  AccountingEvent (immutable record of the financial event)
        │
        ▼
  AccountingEntry + AccountingEntryLine (debit/credit pairs)
        │
        ▼
  Subledger Entries (customer, contract, deposit, corporate)
        │
        ▼
  AccountingPostingBatch (grouped by date, account, cost center)
        │
        ▼
  Export / Acknowledgement → Tenant's ERP/Accounting System

Posting Batch Lifecycle

Security Architecture

JWT Token Structure

Access Token (expires in 60 minutes):

Refresh Token (expires in 7 days):

Security Measures

Database Design Principles

Deployment Architecture

Docker Compose (Local Development)

Environment Configuration

What's Next?

• Getting Started — Log in and explore the interface
• Business Processes — Leads, quotes, reservations, and contracts
• Workflow Configuration — Configure workflows, stages, and transitions