📘 CLAMANS - Leave Management System

CLAMANS is a role-based, workflow-driven Leave Management System developed for the Central Library, IIT Delhi.
The system digitizes and automates the complete leave lifecycle with policy-compliant leave calculations, multi-level approvals, and automated email notifications, ensuring transparency, accuracy, and administrative efficiency.

---

🚀 Key Highlights

• ✅ 4-tier Role-Based Access Control (Staff, HOD, Head, Admin)
• 🔁 Multi-level approval workflow with remarks at each stage
• 📆 Accurate leave computation handling:
  • Weekends
  • Institutional holidays
  • Half-day policies
• 📧 SMTP-based workflow-driven email automation
• 🔐 Email-based OTP verification & secure authentication
• 🗄️ PostgreSQL-backed transactional data layer
• 🎨 Modern Streamlit UI with custom CSS
• ⚙️ Administrative user & leave balance management

---

🧑‍💼 User Roles & Responsibilities

Role	Capabilities
Staff	Apply leave, view leave balance, track leave history
HOD	Review staff leaves, forward or reject with remarks
Head	Final approval or rejection authority
Admin	User creation, role management, leave balance control

---

🔄 Leave Workflow

Staff → HOD → Head → Final Decision → Email Notification Each stage:

• Enforces validation rules
• Captures reviewer remarks
• Sends automated email updates to relevant stakeholders

---

🧠 Leave Calculation Logic

CLAMANS ensures policy compliance using intelligent leave computation logic:

• ❌ Excludes weekends (Saturday & Sunday)
• ❌ Excludes institution-declared holidays
• ➗ Supports half-day leave (0.5 day) rules
• 🚫 Prevents invalid date ranges
• 🔢 Automatically updates leave balance transactionally

Core utility functions:

is_working_day(date, holidays)
calculate_working_days(start_date, end_date, holidays)

---

🗄️ Database Design (PostgreSQL)

CLAMANS uses a normalized, relational PostgreSQL schema designed to ensure data integrity, transactional safety, and institutional policy compliance.

Core Tables

users

• Stores authentication and identity information
• Implements role-based hierarchy using reports_to
• Tracks remaining leave balance per user

Key Fields:

• id (Primary Key)
• username, email, password
• role (staff / hod / head / admin)
• reports_to (Foreign Key → users.id)
• leave_count

---

leaves

• Stores all leave applications and their lifecycle state
• Supports multi-level approval workflow
• Maintains complete audit trail

Key Fields:

• user_id (Foreign Key → users.id)
• leave_type, reason
• start_date, end_date
• status (pending, forwarded, approved, rejected)
• hod_remarks, head_remarks
• reviewed_by, approved_by
• applied_date, forwarded_date, approval_date
• is_half_day
• reference_no

---

otp_verification

• Enables email-based OTP authentication
• Enforces time-bound verification

Key Fields:

• email
• otp
• expiry

---

Database Features

• 🔗 Foreign-key integrity across users and leave records
• 🔒 Transaction-safe leave deductions
• 🧮 Accurate leave balance updates (full-day & half-day)
• 🆔 Unique reference number generation: