# 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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.

```mermaid
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.