Enterprise Approval Engine

A comprehensive file tracking and approval system built with Spring Boot and Spring State Machine. This system automates multi-level approvals for various organisational processes, including leave requests, vendor payments, expense claims, and document approvals.

Features

• Unlike simple status-flagging, this system implements a formal Finite State Machine (FSM) using Spring State Machine. This ensures high data integrity and prevents "illegal" business operations.
• Guards (Validation): The system uses Guards to ensure transitions only happen if specific conditions are met (e.g., an L2 approval cannot be triggered if the L1 signature is missing).
• Actions (Side Effects): Transitions automatically trigger asynchronous actions, such as sending email notifications via Spring Mail or logging audit trails.
• Interceptors: We intercept state changes to persist the current machine state into the H2/PostgreSQL database, ensuring that long-running workflows can survive a system restart.
• SLA & Escalation: Includes logic to transition a request to an ESCALATED state if an approver does not take action within a defined time window.

State Transition Diagram

stateDiagram-v2 [*] --> SUBMITTED SUBMITTED --> PENDING_L1: Submit Request

PENDING_L1 --> PENDING_L2: L1 Approved (Amount > Threshold)
PENDING_L1 --> APPROVED: L1 Approved (Amount <= Threshold)
PENDING_L1 --> REJECTED: L1 Rejected

PENDING_L2 --> APPROVED: L2 Approved
PENDING_L2 --> REJECTED: L2 Rejected
PENDING_L2 --> ESCALATED: No Action (SLA Timeout)

ESCALATED --> APPROVED: Admin Override
REJECTED --> [*]
APPROVED --> [*]

Request Types Supported

• Leave Requests
• Vendor Payments
• Petty Cash Requests
• Document Approvals
• Purchase Orders
• Expense Claims
• Contract Approvals

Technology Stack

• Backend: Spring Boot
• State Machine: Spring State Machine
• Database: H2. You can use any other RDMS like PostgreSQL/MySQL
• Email: Spring Mail
• Build Tool: Maven
• Java version: 21

Installation

• Clone the project

  git clone https://github.com/niyiment/approval-flow/tree/main
  cd approval-flow
  

• Build project

    mvn clean install
  

• Run the application

    mvn spring-boot:run
  

  Open your browser and type in the Swagger URL below:

  http://localhost:8080/swagger-ui/index.html
  

Sample Approval Request

POST /api/approvals
Content-Type: application/json

{
"type": "EXPENSE_CLAIM",
"title": "Business Travel Expenses",
"description": "Travel expenses for client meeting",
"amount": 1200.00,
"submittedBy": "john.doe",
"submitterEmail": "john.doe@company.com",
"department": "SALES",
"priority": "NORMAL"
}