Re_Backend/docs/DATABASE_SCHEMA.md

Database Schema Documentation

1. Overview

This document provides a detailed reference for the backend database schema of the Royal Enfield Workflow Management System.

Database System: PostgreSQL 16.x Schema Conventions:

• Primary Keys: UUID (v4) for all tables.
• Naming: Snake_case for tables and columns.
• Audit Columns: Most tables include created_at, updated_at, created_by, updated_by.
• Soft Deletes: is_deleted flag used on critical entities.

2. Architecture Diagrams (A4 Optimized)

2.1. Core Workflow Architecture

Focuses on the request lifecycle, approval chains, and direct interactions.

erDiagram
  users ||--o{ workflow_requests : "initiates"
  users ||--o{ approval_levels : "approves"
  users ||--o{ participants : "collaborates"
  workflow_requests ||--|{ approval_levels : "has_steps"
  workflow_requests ||--o{ participants : "has_users"
  workflow_requests ||--o{ documents : "contains"
  workflow_requests ||--o{ work_notes : "discussions"
  workflow_requests ||--o{ activities : "audit_trail"
  workflow_templates ||--o{ workflow_requests : "spawns"
  workflow_requests ||--|| conclusion_remarks : "finalizes"

  workflow_requests {
    uuid request_id PK
    varchar request_number
    enum status
    integer current_level
  }
  approval_levels {
    uuid level_id PK
    integer level_number
    enum status
    uuid approver_id FK
  }

2.2. Business Domain Data

Focuses on the specific data payloads (Dealers, Finance, Claims) attached to requests.

erDiagram
  workflow_requests ||--o{ dealers : "context"
  workflow_requests ||--|| dealer_claim_details : "claim_data"
  workflow_requests ||--|| dealer_proposal_details : "proposal"
  workflow_requests ||--|| dealer_completion_details : "evidence"
  workflow_requests ||--o{ dealer_claim_history : "versions"
  
  workflow_requests ||--|| claim_budget_tracking : "financials"
  workflow_requests ||--|| internal_orders : "sap_ref"
  workflow_requests ||--o{ claim_invoices : "billing"
  claim_invoices ||--o{ claim_credit_notes : "adjustments"

  dealer_claim_details {
    uuid claim_id PK
    varchar activity_type
  }
  claim_budget_tracking {
    decimal approved_budget
    decimal final_claim_amount
  }

2.3. System Support Services

Focuses on cross-cutting concerns like logging, notifications, and monitoring.

erDiagram
  users ||--o{ notifications : "receives"
  users ||--o{ system_settings : "configures"
  users ||--o{ audit_logs : "actions"
  
  workflow_requests ||--o{ notifications : "triggers"
  workflow_requests ||--o{ tat_tracking : "monitors_sla"
  workflow_requests ||--o{ tat_alerts : "sla_breaches"
  workflow_requests ||--o{ request_summaries : "ai_summary"
  workflow_requests ||--o{ report_cache : "reporting"
  
  notifications ||--o{ email_logs : "outbound"
  notifications ||--o{ sms_logs : "outbound"

  tat_tracking {
    decimal total_tat_hours
    boolean threshold_breached
  }

3. Schema Modules

3.1. User & Authentication Module

Manages user identities, sessions, and system-wide configurations.

erDiagram
    users ||--o{ user_sessions : "has"
    users ||--o{ subscriptions : "has_device"
    users ||--o{ system_settings : "modifies"

    users {
        uuid user_id PK
        varchar employee_id
        varchar email
        varchar display_name
        enum role
        boolean is_active
    }
    user_sessions {
        uuid session_id PK
        uuid user_id FK
        varchar session_token
        timestamp expires_at
    }
    subscriptions {
        uuid subscription_id PK
        uuid user_id FK
        varchar endpoint
    }

Tables

users Core user registry. synced with Okta/HRMS.

• user_id (PK): Unique UUID.
• employee_id (Unique): HR system ID.
• email (Unique): Official email address.
• role: RBAC role (USER, ADMIN, etc.).
• is_active: Soft delete/account link status.

user_sessions Active JWT sessions for invalidation/tracking.

• session_token: The JWT access token.
• refresh_token: For renewing access tokens.
• device_type: Web/Mobile classification.

system_settings Dynamic configuration (e.g., global TAT thresholds).

• setting_key (Unique): Config identifier name.
• setting_value: The value (text/json).

---

3.2. Workflow Engine Module

The core engine driving request lifecycles, approvals, and tracking.

erDiagram
    workflow_requests ||--|{ approval_levels : "steps"
    workflow_requests ||--o{ activities : "events"
    workflow_requests ||--|{ participants : "access"
    workflow_templates ||--o{ workflow_requests : "spawns"

    workflow_requests {
        uuid request_id PK
        varchar request_number
        enum status
        uuid initiator_id FK
    }
    approval_levels {
        uuid level_id PK
        uuid request_id FK
        integer level_number
        enum status
        uuid approver_id FK
    }

Tables

workflow_requests The central entity representing a business process instance.

• request_number: Human-readable ID (e.g., REQ-2024-001).
• current_level: Pointer to the active approval step.
• status: DRAFT, PENDING, APPROVED, REJECTED, CLOSED.

approval_levels Defines the sequence of approvers for a request.

• level_number: Sequence index (1, 2, 3...).
• approver_id: User responsible for this step.
• tat_hours: SLA for this specific step.
• status: PENDING, APPROVED, REJECTED.

participants Users with visibility/access to the request (spectators, contributors).

• participant_type: SPECTATOR, CONTRIBUTOR.
• can_comment, can_view_documents: Granular permissions.

activities Audit trail of all actions performed on a request.

• activity_type: CREATED, APPROVED, COMMENTED, FILE_UPLOADED.
• metadata: JSON payload with specific details of the event.

workflow_templates Blueprints for creating new requests.

• approval_levels_config: JSON defining the default approver chain structure.

---

3.3. Dealer Management Module

Stores specific data related to dealer claims, onboardings, and performance.

erDiagram
    workflow_requests ||--|| dealer_claim_details : "details"
    workflow_requests ||--|| dealer_proposal_details : "proposal"
    workflow_requests ||--|| dealer_completion_details : "completion"
    workflow_requests ||--o{ dealer_claim_history : "versions"
    workflow_requests ||--o{ dealers : "related_to"

    dealers {
        uuid dealer_id PK
        varchar dealer_name
        varchar sales_code
    }

Tables

dealers Master data for dealerships.

• sales_code, service_code: Dealer unique identifiers.
• dealer_name, region, city: Location details.

dealer_claim_details Specific attributes for a Dealer Claim request.

• activity_name, activity_type: Marketing/Sales activity details.
• period_start_date, period_end_date: Duration of the claim activity.

dealer_proposal_details Stores the initial proposal data for a claim.

• total_estimated_budget: The proposed validation amount.
• proposal_document_url: Link to the uploaded proposal PDF/Doc.

dealer_claim_history Snapshots of the claim data at various approval stages.

• snapshot_data: JSON dump of the claim state.
• version: Incremental version number.

---

3.4. Financial Module

Manages budgeting, internal orders, and invoicing.

erDiagram
    workflow_requests ||--|| claim_budget_tracking : "budget"
    workflow_requests ||--|| internal_orders : "io"
    workflow_requests ||--o{ claim_invoices : "invoices"
    claim_invoices ||--o{ claim_credit_notes : "credit_notes"

Tables

claim_budget_tracking Central ledger for a request's financial lifecycle.

• initial_estimated_budget: Original requested amount.
• approved_budget: Validated amount after approvals.
• io_blocked_amount: Amount reserved in SAP.
• final_claim_amount: Actual payout amount.

internal_orders SAP Internal Order references.

• io_number: The IO code from SAP.
• io_available_balance, io_blocked_amount: Balance tracking.

claim_invoices Invoices submitted against the claim.

• invoice_number: Vendor invoice ID.
• amount: Invoice value.
• dms_number: Document Management System reference.

claim_credit_notes Adjustments/Returns linked to invoices.

• credit_note_amount: Value to be deducted/adjusted.

---

3.5. Ancillary Modules

Support functions like notifications, tracking, and logs.

Tables

notifications User alerts.

• is_read: Read status.
• action_url: Deep link to the relevant request.

tat_tracking Turnaround Time monitoring.

• tracking_type: REQUEST (overall) or LEVEL (step-specific).
• total_tat_hours: The allowed time.
• elapsed_hours: Time consumed so far.
• breached_flags: threshold_50_breached, etc.

tat_alerts Logs of TAT breach notifications sent.

• alert_type: TAT_50, TAT_75, TAT_100.
• is_breached: Confirmed breach status.

request_summaries AI or manually generated summaries of complex requests.

• is_ai_generated: Origin flag.
• description, closing_remarks: Narrative text.