# Employee Leave Management System — Run & Support Guide

Built from `Employee_Leave_Management_Application_Requirement_Document.docx`
on top of the FlowFabric no-code Studio platform, under tenant:

```
tenant_id : 2f92482d-890b-4631-8320-661bcc1bc537
tenant    : Official Leave management
```

Everything below was created by [`backend/scripts/seed_leave_management_app.py`](../backend/scripts/seed_leave_management_app.py)
(re-runnable — it exits early if the `Employee Leave Management System` app
bundle already exists for this tenant; see **Resetting / re-seeding** below).

---

## 1. How the SRS maps onto this platform

FlowFabric is a **Studio**: every "screen" the SRS describes (Employee List,
Apply Leave, Approval Inbox, dashboards, ...) is data you build once in the
Studio, not custom frontend code. This app was built entirely as Studio
artifacts:

| SRS concept | Built as |
|---|---|
| Employees, Departments, Leave Types, Leave Balances (master data) | 4 **Masters** (Datasources), with `reference` fields linking them (Employee → Department → Manager) |
| Apply Leave (SCR-11) | 1 **Form**: "Leave Application", published, with an `on_submit → trigger_workflow` event |
| Leave approval chain, Status Model (§9, §10) | 1 **Workflow**: "Leave Approval Workflow" — `Start → Manager/Team Lead Review → HR Review → Approved/Rejected`, plus a `Send Back` branch |
| Employee / Manager / HR dashboards (§11) | 3 **Dashboards**, each role-restricted, backed by 6 saved **Datasets** (Pending/Approved/Rejected/By Type/By Status/By Department) |
| Notifications (§16) | 2 **Tasks** (automation) + 2 **Scheduled Jobs** (SLA monitor, weekly balance review) + 5 demo **Notifications** |
| RBAC (§4, §5, §6) | 4 new **Roles** (Employee, Team Lead, Department Manager, HR Admin) alongside the existing Administrator |
| Navigation (§7) | A **"Leave Management"** sidebar group (Menu Builder): Apply Leave, Employees, Departments, Leave Types, Leave Balances |

**Platform limitation to know about up front:** every internal user (any
role) signs into the *same* Studio shown to an Administrator — the fixed
left sidebar (Datasources, Forms, Workflows, Dashboards, Tasks, ...) is not
currently hidden or re-skinned per role (the platform enforces permissions
at the API level — an Employee gets a clear permission error on anything
their role can't do — it just doesn't hide the button). So an Employee
won't see a bespoke "Employee Portal" look; they use **Dashboards** for
their KPI view, **Forms → Leave Application** (or the **Leave Management**
sidebar group's **Apply Leave** shortcut) to apply, and **Datasources** to
browse Employees/Leave Types/Leave Balances. Building a dedicated
consumer-style UI would be a platform/frontend enhancement, not something
this data-seeding pass does.

Likewise, **approving/rejecting/sending back** a specific request is done
today from **Workflows → Leave Approval Workflow → Design**, using the
canvas's own "load an instance, advance it" runtime panel (paste the
instance id, pick the next step, add a comment) — there isn't yet a
one-click "Approve" button on a dashboard row. The 9 non-draft dummy leave
requests already have real `workflow_instances` you can open this way to
see the mechanism.

---

## 2. Running the application

Prerequisites: PostgreSQL running with the `flowfabric` database
(`db/schema.sql` already applied), Python 3.11+ with the backend's
`.venv`, Node.js for the frontend.

**Backend** (FastAPI, from `backend/`):
```bash
.venv/Scripts/python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8020 --reload
```

**Frontend** (Vite/React, from `frontend/`):
```bash
npm install
npm run dev
```
Open the printed local URL (defaults to `http://localhost:3001`).

### Signing in

The sign-in screen asks for three things:

| Field | Value |
|---|---|
| Workspace ID | `2f92482d-890b-4631-8320-661bcc1bc537` |
| Email | see the user table below |
| Password | see below (`Leave@123` for every newly created user) |

---

## 3. Users created

Every user below is a brand-new **internal Studio** account (not a Public
Portal / vendor account). Default password for all of them:

```
Leave@123
```

**Change these before any real use** — the platform has no forced
"change password on first login" flow, so rotating them is a manual step
(Studio → **Users** → row menu → **Reset password**, or `PATCH /users/{id}`).

| Name | Email | Role | Notes |
|---|---|---|---|
| Vidyakumar S | vidyakumar.s@saasvaap.com | Administrator | pre-existing — tenant owner, unchanged by this seed |
| Meera Nair | meera.nair@flowfabric-leave.demo | HR Admin | 2nd-level approver, HR module admin |
| Priya Menon | priya.menon@flowfabric-leave.demo | Department Manager | Finance dept. manager, 1st-level approver |
| Rahul Verma | rahul.verma@flowfabric-leave.demo | Team Lead | IT dept. team lead, 1st-level approver |
| Arun Kumar | arun.kumar@flowfabric-leave.demo | Employee | Finance |
| Anu Thomas | anu.thomas@flowfabric-leave.demo | Employee | IT |
| Ravi Das | ravi.das@flowfabric-leave.demo | Employee | HR |
| Divya Iyer | divya.iyer@flowfabric-leave.demo | Employee | Operations |
| Karthik Raj | karthik.raj@flowfabric-leave.demo | Employee | IT |

Each of the 8 non-Administrator users also has a matching **Employee**
master record (Datasources → Employees) linking back to their login via
the `user_account` field, and reports up a department → manager chain:
Finance (Priya), IT (Rahul, reporting to Priya), HR (Meera), Operations
(no assigned manager, deliberately, to show the field is optional).

---

## 4. What got seeded, and where to find it in the Studio

| Studio section | What's there |
|---|---|
| **Datasources** | Departments (4 records), Employees (8), Leave Types (4: Annual/Sick/Casual/Maternity-Paternity), Leave Balances (25, one row per employee × leave type for 2026, `available` is a live formula field) |
| **Forms** | **Leave Application** (published v1) — the Apply Leave screen |
| **Workflows** | **Leave Approval Workflow** (published, 6 steps: Start → Manager/Team Lead Review → HR Review → Approved / Rejected / Sent Back) |
| **Dashboards** | **Employee Leave Dashboard** (Employee role), **Manager Approval Dashboard** (Team Lead + Department Manager), **HR Admin Dashboard** (HR Admin) — Administrator can see all three |
| **Tasks** | **Leave Status Notification** (creates an in-app notification from a template), **Leave Balance Review** (lists Leave Balance records, then notifies) |
| **Scheduled Jobs** | **Leave Approval SLA Monitor** (daily `sla_overdue_scan`), **Monthly Leave Balance Review** (weekly, runs the Leave Balance Review task) |
| **Data Explorer / Datasets** | 6 saved queries backing the dashboard KPIs/charts: Pending / Approved / Rejected Leave Requests, Leave Requests by Type, by Status, Employees by Department |
| **Menu Builder** | "Leave Management" group: Apply Leave, Employees, Departments, Leave Types, Leave Balances (visible to every role) |
| **App Management** | One bundle named **"Employee Leave Management System"** listing every artifact above, for export/promotion to another tenant |

### The 10 dummy leave applications

| App No. | Employee | Leave Type | Dates | Days | Status |
|---|---|---|---|---|---|
| LV-000101 | Arun Kumar | Annual | 15–17 Sep 2026 | 3 | Approved |
| LV-000102 | Anu Thomas | Sick | 16 Sep 2026 | 1 | Submitted (pending Rahul) |
| LV-000103 | Ravi Das | Casual | 20–21 Sep 2026 | 2 | Under Review (manager approved, pending Meera/HR) |
| LV-000104 | Divya Iyer | Annual | 1–5 Oct 2026 | 5 | Approved |
| LV-000105 | Karthik Raj | Sick | 8–9 Sep 2026 | 2 | Rejected (by manager — coverage conflict) |
| LV-000106 | Arun Kumar | Casual | 14 Aug 2026 | 1 | Approved |
| LV-000107 | Anu Thomas | Annual | 22–31 Dec 2026 | 8 | Draft (not yet submitted — no workflow instance) |
| LV-000108 | Ravi Das | Sick | 5 Sep 2026 | 1 | Sent Back (medical certificate requested) |
| LV-000109 | Divya Iyer | Casual | 25–26 Sep 2026 | 2 | Submitted (pending Priya) |
| LV-000110 | Karthik Raj | Maternity/Paternity | 1 Nov 2026 – 30 Jan 2027 | 91 | Approved |

Every non-Draft row has a real `workflow_instances` row plus a
`step_history` audit trail (who acted, when, with what comment) — open it
from **Workflows → Leave Approval Workflow → Design**'s runtime panel using
the instance id, or query it directly for reporting.

---

## 5. Resetting / re-seeding

The seed script is idempotent at the top level: it checks for an `apps` row
named "Employee Leave Management System" on this tenant first and exits
immediately if found, so re-running it is always safe.

To seed again from scratch, delete that `apps` row (Studio → **App
Management**, or `DELETE FROM apps WHERE name = 'Employee Leave Management
System'`) — note this does **not** cascade-delete the masters/form/
workflow/dashboards/users/etc. it referenced; those would need removing by
hand (or via the Studio UI) before re-running, since Roles/Masters/Forms
are unique per `(tenant_id, name)` and the script doesn't upsert past its
own top-level check.

```bash
cd backend
.venv/Scripts/python.exe scripts/seed_leave_management_app.py
```

---

## 6. Known gaps vs. the SRS (platform-level, not fixed by this seed)

- **No forced password reset on first login** and no "temporary password"
  flag exist in the platform — communicate `Leave@123` to each user out of
  band and have them ask an Administrator/HR Admin to reset it once they've
  signed in.
- **No one-click Approve/Reject/Send Back UI** yet outside the Workflow
  Designer's own runtime panel (see §1) — there's no dedicated "Approval
  Inbox" screen with row-level action buttons wired to
  `POST /workflow-instances/{id}/advance`.
- **Dashboards are org-wide, not "my own" views** — a KPI like "My Pending
  Requests" currently counts every pending request tenant-wide, since
  widgets/datasets have no "current signed-in user" filter today.
- **Notifications are tenant-wide**, not per-recipient — the `notifications`
  table has no user/recipient column, so the 5 seeded notifications (and
  anything the two Tasks create) are visible to every signed-in user, not
  just the employee/approver involved.
- **No connectors configured** — real email/SMS delivery needs a Connector
  (Studio → Connectors) with actual SMTP/SMS credentials, which this seed
  deliberately leaves unconfigured (no real credentials to provision).

None of these block using the app for its core purpose — apply, route
through Manager/Team Lead → HR, track balances and status, report on
dashboards — they're just where a production rollout would need real
frontend/platform work beyond what a data-seeding pass can do.