# Functional Requirements & Workflow Document
## Planning & Development (P&D) PC Form Management System

**Document Type:** Functional Requirements & Workflow Specification  
**Purpose:** Source specification for BPMN, UML Activity Diagram, Mermaid Flowchart, or Enterprise Architecture diagrams  
**Scope:** PC Form Management, Approval Workflow, User Management, Meeting Workspace, Messages & Notifications  
**Excluded from Scope:** MEC (Monitoring & Evaluation) workflows, visit plans, M&E reports, and all MEC-related modules  

---

# 1. System Overview

## 1.1 Purpose of the System

The **Planning & Development (P&D) PC Form Management System** (implemented within the Sindh Development Portfolio Management System — PMS) is a centralized digital platform used by the Planning & Development Department of Sindh to manage development project proposals from initial creation through multi-stage review, formal meeting deliberation, chairman authorization, and final approval.

The system replaces paper-based PC (Procurement Case / Project Concept) submissions with a structured, auditable, role-based workflow. It ensures that every development scheme proposal passes through defined checkpoints — Checker, Department Approver, P&D Reviewer, and Chairman — before receiving final approval. All actions are logged, notifications are dispatched automatically, and documents (working papers, meeting notices, advice letters, minutes of meeting) are generated and linked to the relevant PC forms.

The system supports six PC form types, all governed by a **shared approval workflow**:

| PC Form Type | Full Name | Primary Use |
|---|---|---|
| **PC-I** | Project Concept (with CSR) | Initial project concept and feasibility for new schemes |
| **PC-II** | Project Concept Phase II | Detailed feasibility study for new schemes |
| **PC-III(A)** | Annual Work Plan | Annual work planning for ongoing approved schemes |
| **PC-III(B)** | Monthly Progress Report | Monthly progress reporting for ongoing schemes |
| **PC-IV** | Evaluation Report | Evaluation of completed schemes |
| **PC-V** | Completion Report | Final completion reporting for completed schemes |

## 1.2 Main Modules

The system comprises the following primary modules:

| Module | Description |
|---|---|
| **Schemes Management** | Master registry of development schemes (projects) with ADP numbers, UIDs, departments, sectors, and financial data |
| **PC Forms** | Creation, editing, submission, review, approval, and deferral of all six PC form types |
| **Approval Workflow Engine** | State machine governing transitions between Draft → Checker → Department → P&D → Chairman → Approved/Deferred |
| **Meeting Workspace** | Scheduling and management of Pre-PDWP, PDWP, DDWP, and Generic meetings linked to PC forms |
| **User Management** | Users, roles, permissions, designations, sections, and department scope |
| **Notifications** | Workflow-triggered alerts delivered via in-app notification bell and optional email |
| **Messenger** | Direct messaging between users for ad-hoc communication |
| **Documents & Attachments** | File uploads on PC forms, review records, meeting documents, and advice letters |
| **Audit & Review Trail** | Immutable log of every review action (approve, defer, forward) with remarks, signatures, and timestamps |
| **Working Papers** | Auto-generated summary documents for P&D approvers and meeting forums |
| **Dashboard** | Aggregate counts and status overview for PC forms and meetings |

## 1.3 Overall Workflow

The end-to-end workflow for every PC form type follows this sequence:

```
PC Form Creation (Draft)
    ↓
Save Draft / Edit Draft (repeatable)
    ↓
Submit
    ↓
Checker Review (Forwarded for Checking)
    ↓
Department Approval (Forwarded for Approval) — may be skipped
    ↓
P&D Review (Forwarded to P&D)
    ↓
Meeting Process (Pre-PDWP → PDWP → Advice Letter → Forward to Chairman)
    ↓
Chairman Review (Forwarded to Chairman)
    ↓
Decision: Approved OR Deferred
    ↓
[If Deferred] Edit → Resubmit (Modified/Revised) → Re-enter workflow
    ↓
Final Approval
    ↓
Superseded / Inactive (when replaced by revision)
```

## 1.4 Users Involved

| Actor | Role in Workflow |
|---|---|
| **Creator / Submitter** | Department officer who creates and submits PC forms |
| **Checker** | First-line reviewer who verifies completeness and accuracy |
| **Department Approver** | Department-level authority who endorses the submission |
| **P&D Reviewer / Approver** | P&D staff with `can_approve` permission who conduct policy, financial, and technical review |
| **P&D Observer (PnD role)** | Section-scoped P&D users with read-only visibility after checker and department stages complete |
| **Meeting Coordinator / Organizer** | P&D staff who schedule meetings, generate documents, and forward advice to Chairman |
| **Chairman** | Final approving authority who receives forwarded advice and makes the ultimate decision |
| **Meeting Participants** | Invited attendees who acknowledge schedules and co-sign Minutes of Meeting |
| **Administrator** | System admin who manages users, roles, permissions, and configuration |
| **System** | Automated processes: notifications, state transitions, document generation, audit logging |

## 1.5 Approval Hierarchy

The approval hierarchy is strictly sequential with optional skipping:

```
Level 1: Checker (can_check)
    ↓ [may require multiple checkers based on configured count]
Level 2: Department Approver (can_department_approve)
    ↓ [may be skipped if department_required_approvals_count = 0]
    ↓ [may require multiple department approvers]
Level 3: P&D Approver (can_approve)
    ↓ [may require multiple P&D approvers]
Level 4: Meeting Forum (Pre-PDWP → PDWP)
    ↓ [formal deliberation, MoM, advice letter]
Level 5: Chairman (can_approve + forward_chairman recipient)
    ↓ [final single-step approval or deferral]
APPROVED
```

At any level from Checker through Chairman, the reviewer may **Defer** the form, returning it to the submitter for correction.

## 1.6 Shared Services

The following services are shared across all modules:

| Service | Function |
|---|---|
| **PcFormService** | Core workflow engine: submit, approve, reject/defer, revision spawning, eligibility checks |
| **PcFormApprovalCountService** | Computes required reviewer counts per scheme from global and department-scoped user pools |
| **PmsWorkflowNotificationService** | Dispatches notifications at every workflow transition |
| **PmsWorkflowRecipientResolver** | Resolves notification recipients based on role, permission, department scope, and cycle state |
| **MwsAdviseLetterService** | Advice letter generation, editing, and forward-to-chairman |
| **MwsPcFormMeetingDecisionService** | PC approve/defer visibility and MoM signature gating on meeting pages |
| **MwsSchemeMeetingWorkflowHelper** | Meeting type rules, Pre-PDWP/PDWP sequencing, defer-repeat flags |
| **PcFormCoverPageBuilder** | Generates PC form cover page PDFs |
| **Working Paper Service** | Generates working papers linked to meeting types |
| **Permission System (`can()`)** | Role-based access control checked on every action |
| **Signature Service** | Digital signature capture, storage, and validation on approvals |

---

# 2. PC Form Lifecycle

## 2.1 Complete Lifecycle Overview

Every PC form passes through a defined set of states from creation to final disposition. The lifecycle is governed by the `state` field on the `pc_forms` database record and the `status` active flag.

### Active Flag (`status`)

- `status = true` → Active row visible in listings and eligible for workflow actions
- `status = false` → Superseded/inactive row (replaced by a revision, or abandoned post-approval workspace shell)

There is no separate "Archived" database state; superseded forms become inactive (`status = false`) and remain in the database for audit purposes.

## 2.2 State Definitions and Transitions

### State 1: Draft

| Attribute | Value |
|---|---|
| **Database state** | `draft` |
| **UI label** | Draft |
| **Who acts** | Creator / Submitter |
| **Available actions** | Edit, Save Draft, Delete, Submit |
| **Visibility** | Creator and users with list/view permission |

**Entry:** Creator clicks "Generate PC", selects form type, completes wizard steps, and clicks "Save as Draft" without submitting.

**Draft storage:** Drafts may exist as standalone `PcFormDraft` records (not yet linked to a submitted `PcForm` row) or as `PcForm` rows with `state = draft`.

**Exit transitions:**
- **Submit** → `requested` (Forwarded for Checking)
- **Delete** → Record removed

**During Draft:**
- Creator can freely edit all wizard steps
- Scheme linkage is established (one or more schemes per form depending on type)
- Attachments and annexures can be uploaded
- Checklists may be partially completed
- No notifications are generated
- No reviewers are assigned yet

---

### State 2: Submitted / Forwarded for Checking

| Attribute | Value |
|---|---|
| **Database state** | `requested` |
| **UI label** | Forwarded for Checking |
| **Who acts** | Checker(s) |
| **Available actions (Checker)** | Approve, Defer |
| **Available actions (Submitter)** | View only (read-only) |
| **Visibility** | Checkers (org-wide or department-scoped), submitter (own forms) |

**Entry:** Creator clicks **Submit** on the final wizard step (Signatures). System sets `submitted_at` timestamp, resets review counters (`check_count = 0`, `approve_count = 0`, `department_approved_count = 0`), and transitions state to `requested`.

**System actions on submit:**
1. Validates all required fields and checklists
2. Validates scheme eligibility for the PC form type
3. Checks for duplicate in-flight forms on the same scheme
4. Sets workflow counters and thresholds (`required_checks`, `department_required_approvals_count`, `required_approvals`)
5. Dispatches `pc_form_submitted` notification to all eligible checkers (excluding submitter)
6. Records submission in audit trail

**During Forwarded for Checking:**
- One or more checkers review the full PC form in the Details modal
- Each checker may approve once per submission cycle
- When `check_count >= required_checks`, form advances to Department Approval (or directly to P&D if department count is zero)

**Exit transitions:**
- **Checker Approve** (all required checkers done) → `department_approval_pending` OR `under approval` (if no department approvers configured)
- **Checker Defer** → `rejected` (displayed as Deferred)

---

### State 3: Department Approval Pending / Forwarded for Approval

| Attribute | Value |
|---|---|
| **Database state** | `department_approval_pending` |
| **UI label** | Forwarded for Approval |
| **Who acts** | Department Approver(s) |
| **Available actions** | Approve, Defer |
| **Visibility** | Department approvers with overlapping department scope |

**Entry:** All required checker approvals recorded. System dispatches `pc_form_forwarded_department` notification to department approvers.

**Skip condition:** If `department_required_approvals_count = 0` for the scheme's department, this stage is bypassed and the form moves directly to P&D Review.

**During Forwarded for Approval:**
- Department approver verifies the submission against departmental policy
- Department scope is enforced: approver must have department overlap with the scheme's `department_id` or `sub_department_id`
- Each department approver may act once per cycle
- When `department_approved_count >= department_required_approvals_count`, form advances

**Exit transitions:**
- **Department Approve** (all required done) → `under approval` (Forwarded to P&D)
- **Department Defer** → `rejected` (Deferred)

---

### State 4: P&D Review / Forwarded to P&D

| Attribute | Value |
|---|---|
| **Database state** | `under approval` |
| **UI label** | Forwarded to P&D (or Forwarded to Chairman after advice forward) |
| **Who acts** | P&D Approver(s), P&D Observer, Meeting Coordinator |
| **Available actions (P&D Approver)** | Approve, Defer, Generate Working Paper |
| **Available actions (P&D Observer)** | View only (read-only after checker + department complete) |
| **Available actions (Meeting Coordinator)** | Schedule meetings, generate documents, forward advice |

**Entry:** All required department approvals recorded (or stage skipped). System dispatches `pc_form_forwarded_pnd` notification to P&D approvers and section-scoped P&D observers.

**During Forwarded to P&D:**
- P&D approvers conduct policy, financial, and technical review
- Working papers may be generated for meeting forums
- Pre-PDWP and PDWP meetings may be scheduled and linked to the PC form
- P&D approvers may defer with optional "Hold Pre-PDWP meeting again" flag
- Multiple P&D approvers may be required (`approve_count` vs `required_approvals`)

**Sub-state: Forwarded to Chairman**
When advice is forwarded to Chairman via meeting workspace:
- UI label changes to **Forwarded to Chairman**
- Database state remains `under approval`
- `hasChairmanAdviceForwardInCurrentCycle()` returns true
- Chairman recipients see the form in their queue
- P&D can no longer defer from meeting page for forwarded schemes

**Exit transitions:**
- **P&D Approve** (all required done, no meeting path) → `approved`
- **P&D Defer** → `rejected` (Deferred)
- **Meeting → Advice Forward → Chairman Approve** → `approved` (single chairman approval may finalize)
- **Meeting → Advice Forward → Chairman Defer** → `rejected` (Deferred)

---

### State 5: Chairman Review / Forwarded to Chairman

| Attribute | Value |
|---|---|
| **Database state** | `under approval` (with chairman forward flag) |
| **UI label** | Forwarded to Chairman |
| **Who acts** | Chairman (users in `forward_to_user_ids` on forward_chairman review) |
| **Available actions** | Approve, Defer |
| **Visibility** | Chairman recipients only (not all `can_approve` users) |

**Entry path:**
1. PC form reaches P&D stage (`under approval`)
2. Pre-PDWP and/or PDWP meeting held
3. Minutes of Meeting saved and co-signatures collected
4. Advice letter edited per linked PC form
5. P&D organizer clicks **Forward for Advice to Chairman**
6. System creates `PcFormReview` with `action = forward_chairman`
7. Chairman receives `pc_form_advice_forwarded_chairman` notification
8. PC form status label becomes "Forwarded to Chairman"

**During Chairman Review:**
- Chairman reviews Working Paper, MoM, Advice Letter, and full PC form
- MoM signature gate must be complete before approve/defer actions are enabled
- Chairman may approve (finalizes in one step from meeting page) or defer

**Exit transitions:**
- **Chairman Approve** → `approved`
- **Chairman Defer** → `rejected` (Deferred)

---

### State 6: Approved

| Attribute | Value |
|---|---|
| **Database state** | `approved` |
| **UI label** | Approved |
| **Who acts** | None (terminal state for active workflow) |
| **Available actions** | View, Export PDF, Begin Revised PC (post-approval revision) |
| **Visibility** | All authorized users |

**Entry:** Final approval recorded at P&D or Chairman stage. System dispatches `pc_form_approved` notification to submitter, prior reviewers, and P&D participants. External webhook (`bpmsWebhookService->notifyAfterPcApproval()`) may fire.

**During Approved:**
- Form is read-only
- Cover page shows "APPROVED" status
- Post-approval revision workspace may be spawned for PC-I (creates editable shell for Revised PC-I)
- Approved PC forms unlock eligibility for subsequent PC types (e.g., approved PC-I required for PC-III)

**Exit transitions:**
- **Post-approval revision submitted** → New row created with `is_revised = true`, old row `status = false`
- No direct transition back to workflow from approved state without revision

---

### State 7: Deferred

| Attribute | Value |
|---|---|
| **Database state** | `rejected` |
| **UI label** | Deferred |
| **Who acts** | Creator / Submitter |
| **Available actions** | Edit, Save Draft, Resubmit (Delete if still draft-equivalent) |
| **Visibility** | Submitter, all prior reviewers, P&D observers |

**Entry:** Any reviewer (Checker, Department Approver, P&D Approver, Chairman, or P&D from meeting page) clicks **Defer** with required remarks and signature. System creates `PcFormReview` with `action = rejected` and sets `state = rejected`. Notification `pc_form_deferred` sent to submitter with edit deep-link.

**During Deferred:**
- Submitter reads deferral remarks and optional attachment in Details modal
- Submitter edits the form (full edit access restored)
- Deferral history displayed in modal (checker/approver name, remarks, date, attachment)
- Row may show **Modified** label after resubmission (if deferred at approver/P&D stage)

**Exit transitions:**
- **Resubmit** → `requested` (Forwarded for Checking) — workflow restarts from Checker
- Counters reset: `check_count = 0`, `approve_count = 0`, `department_approved_count = 0`
- New submission cycle begins (`submitted_at` updated)

---

### State 8: Modified (Label, Not a Separate State)

| Attribute | Value |
|---|---|
| **Database flag** | `is_modified = true` |
| **UI label** | Modified (badge on row) |
| **Meaning** | Form was resubmitted after deferral at P&D or Chairman stage |

Modified is a **classification label**, not a workflow state. The form's `state` after resubmission is `requested` (Forwarded for Checking), but the row displays a "Modified" badge to indicate this is a resubmission after approver-stage deferral.

---

### State 9: Revised (Label, Not a Separate State)

| Attribute | Value |
|---|---|
| **Database flag** | `is_revised = true`, `parent_id` set |
| **UI label** | Revised (badge on row), optionally "Revised (version N)" |
| **Meaning** | New revision row of a previously approved PC form |

Revised is a **classification label** applied when a new row is spawned from an approved PC form (post-approval revision) or when certain approver-stage rejections create a new revision row instead of same-row resubmit.

---

### State 10: Archived / Superseded (Inactive)

| Attribute | Value |
|---|---|
| **Database flag** | `status = false` |
| **UI label** | Not shown in active listings (hidden) |
| **Meaning** | Row superseded by a newer revision or abandoned workspace shell |

When a revision is submitted, the old row is set to `status = false`. It remains in the database for audit and revision chain tracking (`parent_id`, `rootPcFormId()`) but does not appear in active workflow listings.

---

## 2.3 Lifecycle Diagram (Textual)

```
┌─────────┐
│  DRAFT  │ ←── Create PC Form (any type)
└────┬────┘
     │ Save Draft (repeatable edit cycle)
     │ Submit
     ▼
┌──────────────────────┐
│ FORWARDED FOR        │ ←── Checker Review
│ CHECKING (requested) │     Approve → advance
└────┬─────────┬───────┘     Defer → DEFERRED
     │         │
     │ Approve │ Defer
     ▼         ▼
┌──────────────────────┐   ┌──────────┐
│ FORWARDED FOR        │   │ DEFERRED │
│ APPROVAL (dept)      │   │(rejected)│
└────┬─────────┬───────┘   └────┬─────┘
     │         │                │ Edit + Resubmit
     │ Approve │ Defer          │ (Modified label if approver-stage defer)
     ▼         ▼                ▼
┌──────────────────────┐   ┌──────────────────────┐
│ FORWARDED TO P&D     │   │ FORWARDED FOR        │
│ (under approval)     │   │ CHECKING (re-entry)  │
└────┬─────────┬───────┘   └──────────────────────┘
     │         │
     │         │ Defer
     │         ▼
     │    ┌──────────┐
     │    │ DEFERRED │
     │    └──────────┘
     │
     │ Meeting Path:
     │ Pre-PDWP → PDWP → MoM → Advice Letter → Forward to Chairman
     ▼
┌──────────────────────┐
│ FORWARDED TO         │
│ CHAIRMAN             │
└────┬─────────┬───────┘
     │         │
     │ Approve │ Defer
     ▼         ▼
┌──────────┐ ┌──────────┐
│ APPROVED │ │ DEFERRED │
└──────────┘ └────┬─────┘
                  │ Resubmit → re-enter at CHECKING
                  ▼
            (cycle repeats)
```

---

# 3. Detailed Approval Workflow

## 3.1 Checker Stage

### Responsibilities
- Verify completeness of all wizard sections
- Validate financial figures against scheme data
- Confirm checklist responses are accurate
- Ensure attachments and annexures are present
- Compare submission against department records

### Actions Available
| Action | Effect |
|---|---|
| **Approve** | Increments `check_count`; if threshold met, advances to Department Approval or P&D |
| **Defer** | Sets state to `rejected` (Deferred); requires remarks and signature |

### Possible Decisions
- **Approve** → Form moves to next stage
- **Defer** → Form returns to submitter with remarks

### Data Validation
- Signature required (drawn, uploaded, or saved signature on file)
- Remarks optional on approve; required on defer
- Optional attachment on defer
- User may only act once per submission cycle (`userHasReviewedThisCycle`)
- Permission: `can('pc-forms', 'can_check')`
- Department scope: org-wide or department-scoped checkers

### Returned Cases
When Checker defers:
- Form state → `rejected` (Deferred)
- Submitter notified with remarks
- Submitter edits and resubmits
- Workflow restarts at **Forwarded for Checking**
- `is_modified` remains false (checker-stage defer does not mark as Modified)

---

## 3.2 Department Approver Stage

### Responsibilities
- Verify departmental endorsement of the submission
- Confirm scheme alignment with departmental priorities
- Review checker observations and any modifications
- Endorse or request corrections

### Verification Process
1. Open PC Form Details modal
2. Review all sections (read-only)
3. Check deferral history if resubmission
4. Verify department scope overlap (system enforces automatically)

### Modification Requests
Department approver cannot request partial modifications. The only options are:
- **Approve** → advance
- **Defer** → return to submitter with full remarks

### Approval Process
- Each department approver acts once per cycle
- `department_approved_count` incremented on each approve
- When `department_approved_count >= department_required_approvals_count`, form advances to P&D
- Notification `pc_form_forwarded_pnd` dispatched

### Returned Cases
When Department Approver defers:
- Same as checker defer: state → `rejected`, submitter edits, resubmits at Checking stage
- `is_modified` remains false

### Skip Condition
If `department_required_approvals_count = 0` for the scheme's department configuration, this entire stage is bypassed. After all checker approvals, form goes directly to `under approval` (Forwarded to P&D).

---

## 3.3 P&D Reviewer Stage

### Responsibilities
- Conduct policy review against P&D guidelines
- Perform financial review (cost estimates, phasing, fund sources)
- Conduct technical review (feasibility, benefits, risks)
- Prepare working paper for meeting forums
- Schedule and coordinate Pre-PDWP / PDWP meetings
- Generate advice letter with recommendations
- Forward advice to Chairman

### Policy Review
- Verify compliance with P&D planning policies
- Check scheme eligibility and ADP alignment
- Review justification and objectives

### Financial Review
- Validate cost estimates against scheme allocated amounts
- Review capital/revenue breakdown
- Check fund source allocations and phasing

### Technical Review
- Assess technical feasibility sections
- Review environmental and social safeguards
- Evaluate demand-supply analysis (PC-I)

### Recommendation Process
1. P&D approver reviews PC form in Details modal
2. Generates working paper (type matches meeting: pre-pdwp / pdwp / ddwp)
3. Schedules Pre-PDWP meeting (one per scheme unless defer-repeat flag set)
4. After Pre-PDWP, schedules PDWP meeting (requires at least one Pre-PDWP per linked scheme)
5. Saves Minutes of Meeting; collects co-signatures
6. Edits advice letter per linked PC form
7. Forwards advice to Chairman

### Actions Available
| Action | Context | Effect |
|---|---|---|
| **Approve** | Direct (no meeting path) | Increments `approve_count`; if threshold met → Approved |
| **Defer** | PC Forms modal or Meeting page | State → Deferred; optional Pre-PDWP repeat flag |
| **Generate Working Paper** | P&D stage | Creates PDF summary for meeting |
| **Schedule Meeting** | Meeting Workspace | Links PC form to Pre-PDWP/PDWP/DDWP |
| **Forward Advice** | After PDWP MoM complete | Creates forward_chairman review; notifies Chairman |

### P&D Observer (PnD Role)
- Users with `pnd` role slug see forms at P&D stage in **read-only** mode
- Visibility: section-scoped, after checker + department requirements met
- Cannot approve or defer unless they also have `can_approve` permission
- Receives `pc_form_forwarded_pnd` notification for awareness

### Returned Cases
When P&D defers:
- State → `rejected` (Deferred)
- If deferred from meeting page: `mws_meeting_id` recorded on review
- P&D may set `defer_repeat_pre_pdwp_meeting = true` (allows one additional Pre-PDWP after resubmission)
- On resubmit: `is_modified = true` (Modified label applied)
- Workflow restarts at Checking stage

---

## 3.4 Chairman Stage

### Final Review
Chairman receives forwarded PC forms after:
1. PDWP meeting completed
2. MoM saved and all co-signatures collected
3. Advice letter edited and forwarded

Chairman reviews:
- Full PC form (all wizard sections)
- Working Paper
- Minutes of Meeting
- Advice Letter (P&D recommendation)

### Approval
- Chairman clicks **Approve** in PC Forms Details modal or Meeting page
- Optional remarks and attachment
- Signature required
- From meeting page: `meetingWorkspaceChairmanCompletesApprovalCycle = true` → single approval finalizes form (`approve_count = required_approvals`)
- State → `approved`
- Notification `pc_form_approved` dispatched

### Deferral
- Chairman clicks **Defer** with required remarks and signature
- State → `rejected` (Deferred)
- Same-row resubmit (not new revision row)
- `is_modified = true` on resubmit
- Workflow restarts at Checking stage

### Final Authorization
Chairman is the **final approving authority** in the meeting-based path. Once Chairman approves, the PC form reaches terminal **Approved** state with no further workflow stages.

### Chairman Advisory Response (Non-State-Changing)
A separate `chairman_deferred` review action exists that records an advisory response **without changing workflow state**. This is distinct from the standard Defer action that sets state to `rejected`.

---

## 3.5 All Possible Workflow Paths

### Path A: Straight Approval (No Meeting)
```
Draft → Submit → Checker Approve → [Dept Approve] → P&D Approve → Approved
```

### Path B: Standard Meeting Path
```
Draft → Submit → Checker → Dept → P&D → Pre-PDWP → PDWP → MoM → Advice → Chairman → Approved
```

### Path C: Defer at Checker
```
Draft → Submit → Checker Defer → Edit → Resubmit → Checker → ... → Approved
```

### Path D: Defer at Department
```
... → Dept Defer → Edit → Resubmit → Checker → Dept → ... → Approved
```

### Path E: Defer at P&D (Modified)
```
... → P&D Defer → Edit → Resubmit (Modified) → Checker → ... → Approved
```

### Path F: Defer at Chairman (Modified)
```
... → Chairman Defer → Edit → Resubmit (Modified) → Checker → ... → Approved
```

### Path G: Post-Approval Revision (Revised)
```
Approved → Begin Revised PC → Edit Workspace → Submit (Revised) → Checker → ... → Approved
```

### Path H: Skip Department
```
Draft → Submit → Checker Approve → P&D (dept count = 0) → ... → Approved
```

### Path I: DDWP Meeting (No Pre-PDWP Required)
```
... → P&D → DDWP Meeting → ... (no Pre-PDWP prerequisite)
```

---

# 4. Modified vs Revised

## 4.1 Modified

### Definition
**Modified** indicates that a PC form was **resubmitted after deferral at the P&D approver or Chairman stage**. It is a classification label (`is_modified = true`), not a separate workflow state.

### Minor Corrections Context
While "Modified" in the system specifically tracks approver-stage deferrals, the corrections made may range from minor text changes to substantial financial revisions. The "Modified" label signals to all reviewers that this is a **resubmission after P&D-level deferral**, not a first-time submission.

### Examples
- P&D defers PC-I with remarks: "Revise cost phasing in Section 10"
- Chairman defers with remarks: "Update justification per PDWP minutes"
- Submitter corrects and resubmits → row shows **Modified** badge
- Cover page shows "MODIFIED PC-I"

### Who Requests It
- P&D Approver (via Defer action at `under approval` stage)
- Chairman (via Defer action after advice forward)
- P&D from Meeting Workspace (via defer on meeting page)

### Where the Workflow Returns
**Always restarts at Forwarded for Checking (`requested`)** regardless of which stage deferred. All review counters are reset. The full checker → department → P&D → chairman cycle must be completed again.

### Database Behavior
- **Same row resubmit** (not a new revision row) for P&D and Chairman deferrals
- `is_modified` set to `true` on successful resubmit via `resolveIsModifiedOnSuccessfulResubmit()`
- `parent_id` unchanged
- Old review records from prior cycle ignored for cycle-gating

---

## 4.2 Revised

### Definition
**Revised** indicates a **new revision row** of a previously approved PC form. It is a classification label (`is_revised = true`, `parent_id` pointing to prior row).

### Major Corrections Context
Revised forms represent a new version of an already-approved PC form. This typically involves substantial changes to an approved project concept and requires a full re-approval cycle.

### Examples
- Approved PC-I exists; department needs to submit updated project concept → **Begin Revised PC-I**
- System creates post-approval revision workspace (`post_approval_revision_workspace = true`)
- Submitter edits and submits → new active row with `is_revised = true`
- Old approved row set to `status = false` (superseded)
- Row shows **Revised** badge and version number

### Who Requests It
- Submitter (initiates post-approval revision from approved PC-I)
- System (auto-marks `is_revised = true` on first PC-I submit for already-approved scheme)
- Certain approver-stage rejections that spawn new revision rows (non-P&D defer path)

### How It Differs from Modified

| Aspect | Modified | Revised |
|---|---|---|
| **Trigger** | Defer at P&D/Chairman stage | Post-approval revision or certain rejections |
| **Row behavior** | Same row resubmitted | New row created; old row deactivated |
| **Database flag** | `is_modified = true` | `is_revised = true`, `parent_id` set |
| **Prior state** | Was in workflow (deferred) | Was approved (or approver rejection) |
| **Revision chain** | No parent-child link | Linked via `parent_id` / `rootPcFormId()` |
| **Cover page** | "MODIFIED PC-I" | Standard cover with Revised badge |
| **Eligibility** | Any deferred form | Primarily PC-I (revision chains) |

### Workflow Impact
- Revised forms enter workflow at **Forwarded for Checking** (`requested`)
- `is_modified = false` on post-approval revision resubmit
- Full approval cycle required
- Revision version number computed for index display
- Singleton PC types (PC-II, III, IV, V) do not support revision chains — one active row per scheme

---

# 5. Deferred Workflow

## 5.1 What Deferred Means

In the system, **Deferred** is the user-facing label for the database state `rejected`. There is no separate "permanently rejected" state — all deferrals are **return-to-submitter** actions intended for correction and resubmission.

Every deferral:
1. Sets `pc_forms.state = rejected`
2. Creates a `PcFormReview` record with `action = rejected` and appropriate `type` (check, department, approve)
3. Requires remarks (plain text) and digital signature
4. Optionally accepts an attachment
5. Dispatches `pc_form_deferred` notification to submitter

## 5.2 Who Can Defer

| Stage | State | Permission Required | Additional Conditions |
|---|---|---|---|
| Checker | `requested` | `can_check` | Org-wide or dept-scoped |
| Department Approver | `department_approval_pending` | `can_department_approve` | Department scope overlap |
| P&D Approver | `under approval` | `can_approve` | Org-wide |
| P&D from Meeting (pnd role) | checker/approver slots | `pnd` role slug | Via meeting page; bypasses `can_approve` |
| Chairman from Meeting | after advice forward | `can_approve` + forward recipient | MoM signatures must be complete |
| Chairman from PC Forms modal | `under approval` + forwarded | Forward recipient | Standard defer path |

## 5.3 Reasons for Deferral

Deferral reasons are free-text remarks provided by the reviewer. Common examples:
- Incomplete financial data or incorrect phasing
- Missing attachments or annexures
- Checklist items not adequately addressed
- Figures do not match scheme records
- Justification insufficient per forum minutes
- Technical feasibility concerns
- Policy non-compliance

## 5.4 How Deferred Forms Return into Workflow

1. Submitter receives `pc_form_deferred` notification with deep-link to edit
2. Submitter opens PC Form Details modal → reads deferral remarks and attachment
3. Submitter clicks **Edit** → wizard opens with full edit access
4. Submitter makes corrections → **Save as Draft** (optional) → **Submit**
5. System transitions state to `requested` (Forwarded for Checking)
6. Review counters reset to zero
7. New submission cycle begins (`submitted_at` updated)
8. `is_modified` may be set to `true` (if deferred at approver stage)
9. `pc_form_submitted` notification dispatched to checkers

## 5.5 Whether Meetings May Be Required

Meetings are not automatically required after deferral. However:

- **Pre-PDWP repeat flag:** When P&D defers with "Hold Pre-PDWP meeting again after modified PC is resubmitted" checked, `defer_repeat_pre_pdwp_meeting = true` is set. This allows **one additional Pre-PDWP meeting** for that scheme after the modified form is resubmitted and re-enters the P&D stage. The flag is cleared when a new Pre-PDWP is scheduled.
- **Meeting sequencing rules still apply:** PDWP still requires at least one Pre-PDWP per linked scheme (unless defer-repeat flag grants exception)
- **Defer from meeting page:** P&D may defer directly from the Meeting Workspace page; `mws_meeting_id` is recorded on the review for traceability

## 5.6 How Approval Resumes Afterward

After resubmission, the form follows the **complete approval path** from Checker stage:

```
Resubmit → Checker(s) → Department Approver(s) → P&D → [Meeting] → Chairman → Approved
```

No stages are skipped on resubmission. Each reviewer must act again in the new cycle. Prior-cycle review records are ignored for cycle-gating (`userHasReviewedThisCycle` only considers current cycle).

---

# 6. User Management Module

## 6.1 Users

A **User** represents an individual system account with:
- Name, email, password (authentication credentials)
- `role_id` → linked Role
- `section_id` → linked Section (P&D section-based visibility)
- `designation_id` → linked Designation (displayed in notifications and documents)
- Department scope via `users_departments` pivot (for checkers and department approvers)
- Sub-department scope via `userSubDepartments`
- Digital signature (drawn, uploaded, or on file)
- Profile photo (optional)
- Active/inactive status

## 6.2 Roles

A **Role** defines a user's organizational function:
- Stored with `slug` identifier (e.g., `pnd`, `admin`, `checker`)
- Linked to permissions via `control_access` module configuration
- Seeded demo profiles:
  - **PC Checker** — `list`, `view`, `can_check`
  - **PC Department Approver** — `list`, `view`, `can_department_approve`
  - **PC Approver (P&D)** — `list`, `view`, `can_approve`, Meeting Workspace CRUD
  - **Chairman PD** — Same as PC Approver
  - **Administrator** — Full system access

### Key Role Slug: `pnd`
- P&D role with section-scoped scheme visibility
- Sees all `under approval` forms after checker + department complete
- May set Pre-PDWP repeat flag on defer
- Observer read-only mode unless also has `can_approve`

## 6.3 Permissions

Permissions are module-action pairs stored in `control_access` and checked via `can('module', 'action')`:

### PC Forms Permissions
| Permission | Action |
|---|---|
| `add` | Create / Generate PC forms |
| `edit` | Edit draft and deferred forms |
| `view` | View PC form details |
| `list` | Access PC Forms listing page |
| `can_check` | Checker approve/defer at Checking stage |
| `can_department_approve` | Department approve/defer at Department stage |
| `can_approve` | P&D approve/defer at P&D stage; Chairman actions |
| `export_pdf` | Export PC form PDF |
| `pc1_analyze_ai` | AI analysis tools (PC-I) |
| `pc1_compare_ai` | AI comparison tools (PC-I) |

### Meeting Workspace Permissions
| Permission | Action |
|---|---|
| `add` | Create meetings |
| `edit` | Edit meetings |
| `view` | View meetings |
| `delete` | Delete meetings |

### Other Module Permissions
- **Messages / Messenger** — conversation access
- **Administration** — user management, role configuration, system settings
- **Schemes** — scheme listing and details
- **Field-level permissions** — `canField('pc-forms', 'field_name', 'view|edit')` for granular field access

## 6.4 Designations

A **Designation** is the user's official title (e.g., "Deputy Secretary", "Section Officer", "Chairman P&D"). Displayed in:
- Notification messages ("Name, Designation")
- Meeting documents (notices, MoM, advice letters)
- Signature blocks on approvals
- Participant lists

## 6.5 Sections

A **Section** represents a P&D organizational unit. Sections:
- Link to departments, sub-departments, sectors, sub-sectors, and blocks
- Define scheme visibility for P&D users (`pnd` role)
- Used for section-scoped P&D observer notifications
- Users belong to exactly one section (`section_id`)

## 6.6 Authentication

- Email/password login
- Session-based authentication
- Password reset flow (forgot password)
- First-login password change prompt
- CSRF protection on all forms

## 6.7 Authorization

Authorization is enforced at multiple levels:
1. **Route middleware** — module permission check before controller execution
2. **Controller gates** — `abort_unless(can(...))` on every action
3. **Service-layer rules** — `currentUserMayApprove()`, `currentUserMayReject()`, department scope overlap
4. **Listing scope** — `PcFormService` filters visible rows per role
5. **Cycle gating** — `userHasReviewedThisCycle()` prevents duplicate actions
6. **Field-level** — `canField()` for individual form fields

## 6.8 Profile Management

Users manage their own profile:
- Name and contact details
- Profile photo
- Digital signature (draw, upload, clear, preview)
- Password change
- Signature used automatically on approvals, meeting notices, MoM co-signatures

## 6.9 Relationships Summary

```
User
 ├── belongs to Role (defines permission set)
 ├── belongs to Section (P&D visibility scope)
 ├── belongs to Designation (official title)
 ├── has many UserDepartments (checker/approver scope)
 └── has many UserSubDepartments (sub-dept scope)

Role
 └── has many permissions (via control_access JSON)

Section
 ├── links to Departments
 ├── links to Sectors
 └── links to Blocks

Permission
 └── gates access to: PC Forms, Meeting Workspace, Messages, Administration
```

## 6.10 Role-Based Access Control in Detail

| Role Profile | PC-I | PC-II | PC-III | PC-IV | PC-V | Meetings | Messages | Admin |
|---|---|---|---|---|---|---|---|---|
| Submitter (`add`, `edit`) | Create/Edit/Submit | Create/Edit/Submit | Create/Edit/Submit | Create/Edit/Submit | Create/Edit/Submit | Schedule (if permitted) | Yes | No |
| Checker (`can_check`) | Review/Defer | Review/Defer | Review/Defer | Review/Defer | Review/Defer | View | Yes | No |
| Dept Approver (`can_department_approve`) | Review/Defer | Review/Defer | Review/Defer | Review/Defer | Review/Defer | View | Yes | No |
| P&D Approver (`can_approve`) | Review/Approve/Defer | Review/Approve/Defer | Review/Approve/Defer | Review/Approve/Defer | Review/Approve/Defer | Full CRUD | Yes | No |
| P&D Observer (`pnd` slug) | Read-only at P&D stage | Read-only | Read-only | Read-only | Read-only | Organize/Forward | Yes | No |
| Chairman (`can_approve` + forward) | Final Approve/Defer | Final Approve/Defer | — | — | — | View/Decide | Yes | No |
| Administrator | Full | Full | Full | Full | Full | Full | Full | Full |

---

# 7. Meeting Workspace

## 7.1 Overview

The **Meeting Workspace** (Activity Calendar) is a centralized module for scheduling, conducting, and documenting formal meetings related to PC form approvals. It serves as the bridge between P&D review and Chairman authorization.

## 7.2 Meeting Types

| Type | Normalized Key | Purpose | MoM Signatures Required |
|---|---|---|---|
| **Pre-PDWP** | `pre-pdwp` | Initial screening before full PDWP | 2 (organizer + 1 co-signer) |
| **PDWP** | `pdwp` | Provincial Development Working Party — major approval forum | 4 (organizer + 3 co-signers) |
| **DDWP** | `ddwp` | Department Development Working Party | 2 (organizer + 1 co-signer) |
| **Generic** | `general` | Non-PC administrative meetings | Configurable |

## 7.3 Meeting Creation

### Step 1: Choose Meeting Profile
User clicks "Create meeting" on the planner calendar and selects Pre-PDWP, PDWP, DDWP, or General.

### Step 2: Meeting Details
| Field | Required | Description |
|---|---|---|
| Meeting title | Yes | Official meeting name |
| Meeting type | Yes | Pre-PDWP, PDWP, DDWP, General |
| Date and time | Yes | Start and end time |
| Location | Yes | Venue or "Virtual" |
| Organizer | Yes | Defaults to creating user |
| Status | Yes | Draft or Scheduled |

### Step 3: Link Schemes and PC Forms
For Pre-PDWP, PDWP, and DDWP:
1. Add agenda subjects
2. Select scheme from dropdown
3. Link relevant PC form to agenda row
4. ADP and UID display automatically
5. Repeat for each agenda item
6. **A meeting can be linked to multiple PC forms** (one per agenda subject)

### Step 4: Add Participants
- Select users with roles (organizer, member, co-signatory)
- External participants may be added by name
- Participants receive schedule acknowledgment notifications

### Step 5: Save / Schedule
- Draft: meeting saved but not visible to participants
- Scheduled: participants notified to accept/decline

## 7.4 Meeting Lifecycle Statuses

| Status | Description |
|---|---|
| Draft | Created but not scheduled |
| Scheduled | Published; participants notified |
| Confirmed | All participants accepted |
| Ongoing | Meeting start time reached |
| Completed | Meeting end time passed (auto or manual) |
| Rescheduled | Date/time changed |
| Missed | Meeting time passed without completion |
| Cancelled | Organizer cancelled with reason |

## 7.5 Agenda

- Agenda subjects linked to schemes and PC forms via `mws_meeting_subject_links`
- Each row shows: Scheme name, ADP number, UID, linked PC form
- Multiple subjects per meeting supported
- Subject ordering via `sort_order`

## 7.6 Participants

- Stored in `mws_meeting_participants` with role (organizer, member, co-signatory)
- Schedule acknowledgment: Accept / Decline (with reason)
- Co-signatories must sign MoM before PC approve/defer actions are enabled
- Participant display: name, role badge, acknowledgment status

## 7.7 Documents

| Document | When Generated | Purpose |
|---|---|---|
| **Working Paper** | Before/during meeting | PC form summary for forum deliberation |
| **Meeting Notice** | Before meeting | Official invitation with agenda |
| **Advice Letter** | After PDWP MoM saved | P&D recommendation to Chairman |
| **Minutes of Meeting (MoM)** | After meeting | Official record of deliberations |

### Document Generation Rules
- Working paper type matches meeting type (pre-pdwp / pdwp / ddwp)
- Notice letter sent → `meeting_notice_sent_at` timestamp set
- MoM saved → `mom_saved_at` timestamp set
- Advice letter edited per linked PC form in `advise_letter_overrides`

## 7.8 Attachments

- Meeting-level attachments supported
- Advice letter may include supporting documents
- MoM may reference attached materials
- PC form attachments accessible from meeting context

## 7.9 Discussion

- Meeting detail page shows linked PC forms with workflow status
- PC Review & Decision card shows per-scheme approve/defer actions
- MoM signature gate banner shows remaining co-signatories

## 7.10 Minutes of Meeting (MoM)

### MoM Workflow
1. Organizer saves MoM content (may auto-generate from transcription)
2. Co-signatories listed in `mom_co_signatory_user_ids`
3. Each co-signatory must sign (digital signature)
4. `approve_count_signature` tracked against `required_count_signature`
5. **PC approve/defer from meeting page blocked until all MoM signatures collected**

### MoM Signature Gate
- Required signatures: Pre-PDWP = 2, PDWP = 4, DDWP = 2
- Gate message: "All Minutes of Meeting signatories must sign before this PC can be approved/Deferred"
- Pending co-signatory names displayed on meeting page and PC form modal

## 7.11 Decisions

### Per-Scheme Decisions on Meeting Page
| Action | Who | Condition |
|---|---|---|
| Approve | Chairman (after advice forward) | MoM signatures complete |
| Defer | P&D (before advice forward) or Chairman (after) | MoM signatures complete |
| Forward Advice | P&D organizer | PDWP + Completed + MoM saved |

### Decision Recording
- Approve → `PcFormService::approve()` with optional `meetingWorkspaceChairmanCompletesApprovalCycle`
- Defer → `PcFormService::reject()` with `mws_meeting_id` on review record
- Forward → `MwsAdviseLetterService` creates `forward_chairman` review

## 7.12 Recommendations

- Advice letter contains P&D recommendation text per scheme
- Chairman reviews recommendation before deciding
- Advice letter overrides stored per PC form in meeting record

## 7.13 Action Items

- MoM may contain action items referencing specific PC forms
- Pre-PDWP repeat flag is an action item tied to deferral
- Schedule PDWP action available after Pre-PDWP completion

## 7.14 Meeting History

- Meeting record persists with all statuses (including cancelled/rescheduled)
- Full audit trail of status changes
- Linked PC form reviews reference `mws_meeting_id`
- Meeting planner calendar shows historical meetings

## 7.15 How Meetings Interact with PC Forms

```
PC Form at P&D stage (under approval)
    ↓
Schedule Pre-PDWP Meeting → link PC form to agenda
    ↓
Pre-PDWP held → MoM saved → co-signatures collected
    ↓
Schedule PDWP Meeting → link same PC form
    ↓
PDWP held → MoM saved → co-signatures collected
    ↓
Generate Advice Letter → edit per PC form
    ↓
Forward for Advice to Chairman
    ↓
Chairman reviews in PC Forms modal or Meeting page
    ↓
Chairman Approve or Defer
```

### Meeting Sequencing Rules
| Rule | Description |
|---|---|
| Pre-PDWP | One per scheme unless `defer_repeat_pre_pdwp_meeting` flag |
| PDWP | Requires at least one Pre-PDWP per linked scheme |
| DDWP | No Pre-PDWP prerequisite |
| Multiple PC forms | One meeting can link multiple PC forms (one per agenda subject) |
| Schedule from PC Forms | "Schedule Meeting" button on PC Form Details modal pre-fills meeting create form |

## 7.16 How Approvals May Require Meetings

Meetings are required in the standard approval path for major PC forms (especially PC-I):
- P&D approver does not directly approve major cases without forum deliberation
- Pre-PDWP screens the submission
- PDWP provides formal approval forum
- Advice letter captures forum recommendation
- Chairman gives final authorization based on forum output

Direct P&D approval (without meeting) is possible when configured but the meeting path is the standard process.

## 7.17 Meeting Outcomes

| Outcome | Effect on PC Form |
|---|---|
| Advice forwarded to Chairman | Status label → "Forwarded to Chairman"; Chairman notified |
| Chairman approves from meeting | State → `approved` |
| P&D defers from meeting | State → `rejected` (Deferred); Pre-PDWP repeat flag optional |
| Chairman defers from meeting | State → `rejected` (Deferred); Modified on resubmit |
| Meeting cancelled | No effect on PC form workflow state |
| MoM signatures incomplete | Approve/Defer buttons disabled on meeting page |

---

# 8. Messages Module

## 8.1 Overview

The system provides two communication channels:
1. **Workflow Notifications** — automated, system-generated alerts tied to workflow events
2. **Messenger** — user-initiated direct messaging between individuals

## 8.2 Workflow Notifications

### Notification Types

| Type Key | Trigger Event | Recipients |
|---|---|---|
| `pc_form_submitted` | PC form submitted | Checkers (not submitter) |
| `pc_form_forwarded_department` | Checker stage complete | Department approvers |
| `pc_form_forwarded_pnd` | Department stage complete | P&D approvers + section P&D observers |
| `pc_form_approved` | Final approval | Submitter, prior reviewers, P&D participants |
| `pc_form_deferred` | Any defer action | Submitter (with edit deep-link), downstream participants |
| `pc_form_advice_forwarded_chairman` | Advice forwarded to Chairman | Chairman recipients |
| `mws_meeting_schedule_ack` | Meeting scheduled | Invited participants |
| `mws_meeting_notice_sign_reminder` | Notice letter sent | Participants requiring signature |
| `mws_mom_co_signatory_signature_request` | MoM saved | Co-signatories pending signature |
| `msgr_new_message` | New messenger message | Conversation participants |

### Notification Delivery
- **In-app bell icon** — dropdown with recent unread notifications
- **Notifications page** — full list with filters (All/Unread/Read, period, search)
- **Mark as read** — individual or bulk
- **Deep links** — each notification links to the relevant PC form, meeting, or record
- **Email** — optional email delivery (configurable)

### Notification Content
Each notification includes:
- Title (action summary)
- Message (detail with scheme UID, form type, actor name)
- Type label (e.g., "PC-I advice", "Visit plan")
- Icon and color coding
- Timestamp (relative and absolute)
- Action URL (deep-link to relevant record)

## 8.3 Messenger (Direct Messages)

### Features
- User-to-user conversations
- Message threads with replies
- File attachments on messages
- Reactions on messages
- Presence indicators (online/offline)
- Unread count badge
- Conversation search

### Routes
- `/messenger` — main messenger interface
- Conversation CRUD, message send/receive, attachment upload

## 8.4 How Every Workflow Stage Generates Notifications

| Workflow Transition | Notification Type | Who Is Notified |
|---|---|---|
| Draft → Submitted | `pc_form_submitted` | Checkers |
| Checking → Department | `pc_form_forwarded_department` | Department approvers |
| Department → P&D | `pc_form_forwarded_pnd` | P&D approvers, P&D observers |
| P&D → Approved | `pc_form_approved` | Submitter, all prior reviewers |
| Any stage → Deferred | `pc_form_deferred` | Submitter (with edit link), reviewers |
| Advice → Chairman | `pc_form_advice_forwarded_chairman` | Chairman |
| Meeting scheduled | `mws_meeting_schedule_ack` | Participants |
| Notice sent | `mws_meeting_notice_sign_reminder` | Signers |
| MoM saved | `mws_mom_co_signatory_signature_request` | Co-signatories |
| Chairman → Approved | `pc_form_approved` | All participants |

## 8.5 Communication Between Modules

```
Users ←→ Messenger ←→ Users (ad-hoc)
Users ←→ Notifications ←→ PC Forms (workflow-driven)
Users ←→ Notifications ←→ Meeting Workspace (schedule, MoM, advice)
PC Forms → Notifications → Approvers (submission, deferral)
Meeting Workspace → Notifications → Chairman (advice forward)
Meeting Workspace → Notifications → Participants (schedule, MoM)
System → Notifications → All authorized users (status changes)
```

---

# 9. Module Relationships

## 9.1 Module Interaction Map

```
┌─────────────────┐     ┌──────────────────┐     ┌───────────────────┐
│  User Management │────→│    PC Forms      │←───→│ Meeting Workspace │
│  (Roles, Perms)  │     │  (6 form types)  │     │  (Pre-PDWP/PDWP)  │
└────────┬────────┘     └────────┬─────────┘     └─────────┬─────────┘
         │                       │                         │
         │              ┌────────┴─────────┐               │
         │              │ Approval Workflow │               │
         │              │     Engine        │←──────────────┘
         │              └────────┬─────────┘
         │                       │
    ┌────┴─────┐     ┌──────────┴──────────┐     ┌─────────────────┐
    │ Messages  │←───│   Notifications     │────→│  Documents &    │
    │(Messenger)│     │   (Workflow Alerts) │     │  Attachments    │
    └──────────┘     └─────────────────────┘     └─────────────────┘
                              │
                     ┌────────┴────────┐
                     │   Audit Logs     │
                     │ (PcFormReview)   │
                     └─────────────────┘
```

## 9.2 PC Forms ↔ User Management
- Permissions determine who can create, edit, view, check, approve, or defer
- Department scope filters which forms a checker/approver sees
- Section scope filters P&D observer visibility
- Designation appears on signatures and notifications
- Role slug (`pnd`) triggers special behavior (observer mode, Pre-PDWP repeat flag)

## 9.3 PC Forms ↔ Meeting Workspace
- PC forms linked to meeting agenda via `mws_meeting_subject_links`
- Meeting page shows PC Review & Decision card per linked form
- Approve/Defer on meeting page delegates to `PcFormService`
- Working paper generated from PC form data for meeting type
- Advice letter references linked PC form content
- MoM signature gate controls PC decision actions on meeting page
- "Schedule Meeting" button on PC Form Details modal pre-fills meeting create

## 9.4 PC Forms ↔ Messages/Notifications
- Every workflow transition dispatches notification via `PmsWorkflowNotificationService`
- Recipient resolution via `PmsWorkflowRecipientResolver` (permissions + scope + cycle)
- Defer notifications include edit deep-link for submitter
- Chairman advice notifications deep-link to PC form or meeting

## 9.5 PC Forms ↔ Documents/Attachments
- PC form wizard sections support file attachments
- Review records (approve/defer) support optional attachments
- Cover page PDF generated from form data
- Working paper PDF generated for meeting forums
- Advice letter document generated per scheme
- Annexures on rich text fields

## 9.6 PC Forms ↔ Audit Logs
- Every `PcFormReview` record is an immutable audit entry
- Fields: `pc_form_id`, `user_id`, `type` (check/department/approve), `action` (approve/rejected/forward_chairman/deferred), `remarks`, `attachment`, `signature`, `mws_meeting_id`, `forward_to_user_ids`, `created_at`
- Review history displayed in PC Form Details modal
- Deferral history shown as alert in modal

## 9.7 Meeting Workspace ↔ User Management
- Organizer must have Meeting Workspace permissions
- Participants resolved from user accounts
- Co-signatories must be system users with signature on file
- Chairman resolved by role/permission lookup

## 9.8 Dependencies

| Module | Depends On |
|---|---|
| PC Forms | User Management (auth), Schemes (project data), Approval Engine |
| Approval Engine | User Management (permissions), PcFormReview (audit) |
| Meeting Workspace | PC Forms (linked forms), User Management (participants), Documents |
| Notifications | PC Forms (events), Meeting Workspace (events), User Management (recipients) |
| Messenger | User Management (users) |
| Working Papers | PC Forms (data), Meeting Workspace (type) |
| Advice Letters | PC Forms (data), Meeting Workspace (meeting context) |

---

# 10. Workflow Scenarios

## Scenario 1: Create PC-I → Submit → Approve → Final Approval

### Actors
- **Submitter** (department officer, `add` permission)
- **Checker** (`can_check`)
- **Department Approver** (`can_department_approve`)
- **P&D Approver** (`can_approve`)
- **Meeting Coordinator** (P&D organizer)
- **Chairman** (forward recipient)

### Steps
1. Submitter navigates to PC Forms → clicks **Generate PC** → selects **PC-I**
2. Completes all 17 wizard steps (General, Location, Financial, etc.)
3. Completes checklists and signatures on final step
4. Clicks **Submit** → state becomes `requested` (Forwarded for Checking)
5. Checker receives notification → opens Details modal → reviews all sections → clicks **Approve**
6. If multiple checkers required, each approves in turn until threshold met
7. State advances to `department_approval_pending` (Forwarded for Approval)
8. Department Approver receives notification → reviews → clicks **Approve**
9. State advances to `under approval` (Forwarded to P&D)
10. P&D Approver receives notification → reviews → schedules Pre-PDWP meeting
11. Pre-PDWP held → MoM saved → co-signatures collected
12. P&D schedules PDWP meeting → PDWP held → MoM saved → co-signatures collected
13. P&D edits advice letter → clicks **Forward for Advice to Chairman**
14. Chairman receives notification → reviews MoM, advice letter, working paper, PC form
15. Chairman clicks **Approve** with signature → state becomes `approved`
16. Submitter and all reviewers receive `pc_form_approved` notification

### Final State
- PC form: `state = approved`, `status = true`
- Approved PC-I unlocks eligibility for PC-III on the same scheme

---

## Scenario 2: Create PC-III(A) → Deferred → Modified → Resubmitted → Approved

### Actors
- **Submitter**, **Checker**, **Department Approver**, **P&D Approver**

### Steps
1. Submitter creates PC-III(A) for an ongoing approved scheme (approved PC-I exists)
2. Completes short wizard → submits → Forwarded for Checking
3. Checker approves → Forwarded for Approval
4. Department Approver approves → Forwarded to P&D
5. P&D Approver reviews → finds issues → clicks **Defer** with remarks: "Update annual targets in Section 3"
6. State → `rejected` (Deferred); submitter notified
7. Submitter opens notification → reads remarks → clicks **Edit**
8. Corrects Section 3 → saves → resubmits
9. State → `requested` (Forwarded for Checking); `is_modified = true` (Modified badge shown)
10. Checker reviews Modified submission → approves
11. Department Approver approves
12. P&D Approver approves → state → `approved`

### Final State
- PC-III(A): `state = approved`, `is_modified = true`
- Full re-review cycle completed

---

## Scenario 3: Create PC-IV → Deferred → Revised → Meeting → Approved

### Actors
- **Submitter**, **Checker**, **P&D Approver**, **Meeting Coordinator**, **Chairman**

### Steps
1. Submitter creates PC-IV for a completed scheme (approved PC-I exists)
2. Submits → Checker approves → Department approves → Forwarded to P&D
3. P&D defers: "Evaluation methodology needs revision"
4. Submitter edits and resubmits (Modified)
5. Checker approves → P&D reviews again
6. P&D schedules Pre-PDWP → Pre-PDWP held → MoM saved
7. P&D schedules PDWP → PDWP held → MoM saved → co-signatures collected
8. P&D edits advice letter → forwards to Chairman
9. Chairman reviews → approves with signature
10. State → `approved`

### Final State
- PC-IV: `state = approved`
- Meeting records linked via `mws_meeting_id` on review records

---

## Scenario 4: Chairman Requests Revision → Form Updated → Approval Restarted

### Actors
- **Submitter**, **Checker**, **Department Approver**, **P&D**, **Chairman**

### Steps
1. PC-I has progressed through full meeting path
2. Advice forwarded to Chairman → status: Forwarded to Chairman
3. Chairman reviews and clicks **Defer**: "Revise financial phasing per PDWP minutes Item 4"
4. State → `rejected` (Deferred); submitter notified with Chairman's remarks
5. Submitter edits PC-I → corrects financial phasing → resubmits
6. `is_modified = true`; state → `requested` (Forwarded for Checking)
7. Full cycle restarts: Checker → Department → P&D → Meeting → Chairman
8. Chairman reviews corrected form → approves
9. State → `approved`

### Key Points
- Chairman defer uses same-row resubmit (not new revision row)
- Modified label applied
- All review counters reset
- Meeting may need to be re-held (new Pre-PDWP if defer-repeat flag was set)

---

## Scenario 5: Meeting Generates Action Items → Form Updated → Approval Completed

### Actors
- **P&D Organizer**, **Meeting Participants**, **Co-signatories**, **Chairman**, **Submitter**

### Steps
1. PDWP meeting held for PC-I with multiple agenda subjects
2. MoM records deliberations and action items per scheme
3. Co-signatories sign MoM (4 signatures required for PDWP)
4. P&D organizer reviews MoM action items
5. One scheme's PC form needs update per MoM direction
6. P&D defers that PC form from meeting page with MoM reference in remarks
7. Submitter updates PC form per MoM action items → resubmits
8. Re-enters workflow at Checking stage
9. Progresses through Checker → Department → P&D
10. New PDWP meeting scheduled (or existing meeting updated)
11. MoM for new meeting saved → advice letter updated → forwarded to Chairman
12. Chairman approves → PC form approved

### Key Points
- MoM action items drive deferral reasons
- `mws_meeting_id` on defer review links action to specific meeting
- Pre-PDWP repeat flag may be set if re-screening needed
- Meeting generates formal record chain for audit

---

# 11. State Definitions

| State | DB Value | UI Label | Description | Who Acts | Terminal? |
|---|---|---|---|---|---|
| **Draft** | `draft` | Draft | Form created but not submitted; freely editable | Creator | No |
| **Submitted** | `requested` | Forwarded for Checking | Submitted and awaiting checker review | Checker | No |
| **Pending Checker** | `requested` | Forwarded for Checking | Same as Submitted; awaiting checker action | Checker | No |
| **Pending Department Approval** | `department_approval_pending` | Forwarded for Approval | Checker stage complete; awaiting department approver | Dept Approver | No |
| **Pending P&D Review** | `under approval` | Forwarded to P&D | Department stage complete (or skipped); awaiting P&D | P&D Approver | No |
| **Pending Chairman Approval** | `under approval` | Forwarded to Chairman | Advice forwarded; awaiting Chairman decision | Chairman | No |
| **Modified** | *(flag `is_modified`)* | Modified | Label on resubmitted form after P&D/Chairman defer | — | No |
| **Revised** | *(flag `is_revised`)* | Revised | Label on new revision row of approved form | — | No |
| **Deferred** | `rejected` | Deferred | Returned to submitter for correction | Creator | No |
| **Approved** | `approved` | Approved | Final approval recorded; read-only | None | Yes |
| **Archived/Superseded** | `status = false` | *(hidden)* | Replaced by revision; inactive but retained for audit | None | Yes |
| **Legacy Checking** | `checking` | *(filter only)* | Legacy listing filter bucket; not set on new submissions | — | No |

---

# 12. Actors

## 12.1 Creator / Submitter

| Attribute | Detail |
|---|---|
| **Responsibilities** | Create PC forms, complete wizard, upload documents, submit, respond to deferrals, resubmit |
| **Permissions** | `add`, `edit`, `view`, `list` |
| **Actions** | Generate PC, Save Draft, Edit, Submit, Delete (draft only), View, Respond to deferral |
| **Restrictions** | Cannot approve or defer; read-only after submit until deferred; one in-flight form per scheme (singleton types) |

## 12.2 Checker

| Attribute | Detail |
|---|---|
| **Responsibilities** | First-line review of submitted PC forms for completeness and accuracy |
| **Permissions** | `can_check`, `view`, `list` |
| **Actions** | Approve (advance), Defer (return with remarks) |
| **Restrictions** | One action per cycle; department-scoped or org-wide; cannot edit form data |

## 12.3 Department Approver

| Attribute | Detail |
|---|---|
| **Responsibilities** | Departmental endorsement of checked submissions |
| **Permissions** | `can_department_approve`, `view`, `list` |
| **Actions** | Approve (advance), Defer (return with remarks) |
| **Restrictions** | Department scope overlap required; one action per cycle; only sees forms after checker requirements met |

## 12.4 P&D Reviewer / Approver

| Attribute | Detail |
|---|---|
| **Responsibilities** | Policy, financial, and technical review; working paper generation; meeting coordination; advice letter preparation |
| **Permissions** | `can_approve`, `view`, `list`, Meeting Workspace CRUD |
| **Actions** | Approve, Defer, Generate Working Paper, Schedule Meeting, Edit Advice Letter, Forward to Chairman |
| **Restrictions** | One approve per cycle; org-wide visibility at P&D stage; cannot approve post-approval revision workspaces |

## 12.5 P&D Observer (PnD Role)

| Attribute | Detail |
|---|---|
| **Responsibilities** | Monitor PC forms at P&D stage within section scope |
| **Permissions** | `view`, `list` (section-scoped) |
| **Actions** | View only; organize meetings if also meeting organizer |
| **Restrictions** | Read-only at P&D stage; cannot approve/defer unless also has `can_approve` |

## 12.6 Chairman

| Attribute | Detail |
|---|---|
| **Responsibilities** | Final review and authorization of PC forms forwarded via advice letter |
| **Permissions** | `can_approve` + must be in `forward_to_user_ids` on forward_chairman review |
| **Actions** | Approve (final), Defer (return with remarks), View MoM/Advice/Working Paper |
| **Restrictions** | Only sees forms explicitly forwarded; MoM signatures must be complete for meeting-page actions; single approval finalizes |

## 12.7 Administrator

| Attribute | Detail |
|---|---|
| **Responsibilities** | User management, role/permission configuration, system settings, department/section setup |
| **Permissions** | Full administrative access |
| **Actions** | CRUD users, assign roles, configure permissions, manage sections/designations |
| **Restrictions** | Should not act as workflow reviewer (separation of duties) |

## 12.8 Meeting Coordinator / Organizer

| Attribute | Detail |
|---|---|
| **Responsibilities** | Schedule meetings, manage participants, generate documents, save MoM, forward advice |
| **Permissions** | Meeting Workspace `add`, `edit`; typically P&D approver or P&D observer |
| **Actions** | Create meeting, add participants, generate notice/working paper/advice/MoM, forward advice |
| **Restrictions** | Must be meeting organizer for organizer-only actions; MoM signatures required before PC decisions |

## 12.9 Meeting Participants

| Attribute | Detail |
|---|---|
| **Responsibilities** | Attend meetings, acknowledge schedule, co-sign MoM |
| **Permissions** | Meeting Workspace `view` |
| **Actions** | Accept/Decline schedule, Sign MoM (co-signatories) |
| **Restrictions** | Cannot approve/defer PC forms; co-signatories must sign before PC decisions enabled |

## 12.10 System

| Attribute | Detail |
|---|---|
| **Responsibilities** | Automated state transitions, notification dispatch, document generation, audit logging, eligibility validation, counter management |
| **Actions** | Submit validation, counter increment, state transition, notification dispatch, webhook trigger, meeting auto-complete |
| **Restrictions** | Cannot override business rules; acts only on validated user actions |

---

# 13. Business Rules

## 13.1 Submission Rules
1. Only users with `add` permission can create PC forms.
2. Only users with `edit` permission can edit draft or deferred forms.
3. Submit requires all mandatory fields, checklists, and signatures completed.
4. Cannot submit duplicate in-flight PC-II, PC-III, PC-IV, or PC-V for the same scheme.
5. Cannot create new PC-I if an approved PC-I exists (must use Revised PC-I path).
6. Cannot start new PC-I while another PC-I is in workflow for the same scheme.
7. PC-III(A/B) requires an approved PC-I on the scheme.
8. PC-IV requires a completed scheme with approved PC-I.
9. PC-V requires an approved PC-IV on the scheme.
10. PC-I is for New schemes; PC-III/IV/V are for On-Going/Completed schemes.

## 13.2 Approval Rules
11. Only users with `can_check` can approve/defer at Checking stage.
12. Only users with `can_department_approve` can approve/defer at Department stage.
13. Only users with `can_approve` can approve/defer at P&D stage.
14. Chairman is the final approving authority in the meeting-based path.
15. Each reviewer may act only once per submission cycle.
16. Multiple reviewers may be required at each stage (configurable per scheme).
17. Department approval stage may be skipped if `department_required_approvals_count = 0`.
18. Post-approval revision workspaces cannot be approved or deferred.
19. Inactive rows (`status = false`) cannot be approved.
20. Chairman approval from meeting page may finalize in a single step.

## 13.3 Deferral Rules
21. Defer requires remarks (plain text) and digital signature.
22. Defer sets state to `rejected` (displayed as Deferred) — no permanent rejection.
23. Deferred forms are editable by the submitter.
24. Resubmission always restarts workflow at Checking stage.
25. Checker/Department defer does not set `is_modified`.
26. P&D/Chairman defer sets `is_modified = true` on resubmit.
27. P&D may set `defer_repeat_pre_pdwp_meeting` flag on defer.
28. Deferred forms cannot be directly archived — they must be resubmitted or abandoned.

## 13.4 Modified and Revised Rules
29. Modified forms restart from Checker stage.
30. Revised forms are new rows; old row becomes inactive (`status = false`).
31. Revised forms restart from Checker stage with `is_revised = true`.
32. Post-approval revision creates workspace shell before spawning real revision row.
33. Only PC-I supports revision chains (parent-child via `parent_id`).
34. Singleton types (PC-II, III, IV, V) allow one active row per scheme.

## 13.5 Meeting Rules
35. Meetings can be linked to multiple PC forms (one per agenda subject).
36. Pre-PDWP: one per scheme unless `defer_repeat_pre_pdwp_meeting` flag.
37. PDWP requires at least one Pre-PDWP per linked scheme.
38. DDWP has no Pre-PDWP prerequisite.
39. MoM signatures must be complete before PC approve/defer from meeting page.
40. Advice letter must be edited before forwarding to Chairman.
41. After advice forwarded, P&D cannot defer from meeting page for that scheme.
42. Chairman must be in `forward_to_user_ids` to see and act on forwarded forms.
43. "Schedule Meeting" button hidden for P&D on deferred PC forms.

## 13.6 Notification Rules
44. Notifications are generated at every workflow transition.
45. Notifications respect role, permission, and department scope for recipients.
46. Submitter is excluded from their own submission notification.
47. Defer notifications include edit deep-link for submitter.
48. Already-reviewed users are excluded from forward notifications in same cycle.

## 13.7 Access Control Rules
49. Permissions are role-based via `control_access` module.
50. Users belong to one Section (P&D visibility).
51. Users have one Designation (displayed on documents).
52. Checkers and department approvers have department scope via `users_departments`.
53. P&D observers (`pnd` slug) have section-scoped read-only visibility.
54. Chairman visibility is per-forward (not all `can_approve` users see chairman queue).
55. Listing scope filters forms per role (submitter sees own, checker sees in-progress, etc.).

## 13.8 Document Rules
56. Working paper type matches meeting type (pre-pdwp / pdwp / ddwp).
57. Cover page PDF available for all PC form types.
58. Advice letter overrides stored per PC form per meeting.
59. Review attachments stored on `PcFormReview` records.
60. Signatures required on all approve and defer actions.

## 13.9 Audit Rules
61. Every review action creates an immutable `PcFormReview` record.
62. Review records include: user, type, action, remarks, attachment, signature, timestamp.
63. Meeting-linked reviews include `mws_meeting_id`.
64. Chairman forward reviews include `forward_to_user_ids`.
65. Revision chain tracked via `parent_id` and `rootPcFormId()`.

---

# 14. Final Summary

## Complete Textual Workflow Representation

```
═══════════════════════════════════════════════════════════════════
                    PC FORM MANAGEMENT SYSTEM
              Complete Workflow — Textual Representation
═══════════════════════════════════════════════════════════════════

PHASE 1: CREATION
─────────────────
Actor: Creator/Submitter
  │
  ├─ Navigate to PC Forms → Generate PC
  ├─ Select form type (PC-I, PC-II, PC-III(A), PC-III(B), PC-IV, PC-V)
  ├─ System validates scheme eligibility for selected type
  ├─ Complete wizard steps (varies by type: 17 steps for PC-I, short wizard for others)
  ├─ Upload attachments and annexures
  ├─ Complete checklists (where applicable)
  │
  ├─ [SAVE DRAFT] → State: Draft (repeatable edit cycle)
  │
  └─ [SUBMIT] → State: Forwarded for Checking
       ├─ System validates all required fields
       ├─ Sets submitted_at, resets review counters
       ├─ Computes required reviewer thresholds
       └─ Notification: pc_form_submitted → Checkers

PHASE 2: CHECKER REVIEW
────────────────────────
Actor: Checker(s)
  │
  ├─ Receives notification → Opens PC Form Details modal
  ├─ Reviews all wizard sections (read-only)
  ├─ Reviews attachments, checklists, financial data
  │
  ├─ [APPROVE] → Increments check_count
  │    ├─ If check_count < required_checks → Awaits more checkers
  │    └─ If check_count >= required_checks →
  │         ├─ If department_required > 0 → State: Forwarded for Approval
  │         │    └─ Notification: pc_form_forwarded_department → Dept Approvers
  │         └─ If department_required = 0 → State: Forwarded to P&D (skip dept)
  │              └─ Notification: pc_form_forwarded_pnd → P&D Approvers
  │
  └─ [DEFER] → State: Deferred
       ├─ Remarks required, signature required
       ├─ Notification: pc_form_deferred → Submitter
       └─ → GO TO PHASE 7 (Deferred/Resubmission)

PHASE 3: DEPARTMENT APPROVAL
─────────────────────────────
Actor: Department Approver(s)
  │  [SKIPPED if department_required_approvals_count = 0]
  │
  ├─ Receives notification → Reviews form
  ├─ Department scope overlap enforced
  │
  ├─ [APPROVE] → Increments department_approved_count
  │    ├─ If count < required → Awaits more approvers
  │    └─ If count >= required → State: Forwarded to P&D
  │         └─ Notification: pc_form_forwarded_pnd → P&D Approvers + Observers
  │
  └─ [DEFER] → State: Deferred → GO TO PHASE 7

PHASE 4: P&D REVIEW
────────────────────
Actor: P&D Approver / P&D Observer
  │
  ├─ P&D Approver reviews policy, financial, technical aspects
  ├─ P&D Observer monitors (read-only, section-scoped)
  │
  ├─ [APPROVE directly] → Increments approve_count
  │    └─ If count >= required → State: APPROVED → GO TO PHASE 8
  │
  ├─ [DEFER] → State: Deferred (Modified on resubmit)
  │    ├─ Optional: Set defer_repeat_pre_pdwp_meeting flag
  │    └─ → GO TO PHASE 7
  │
  └─ [MEETING PATH] → GO TO PHASE 5

PHASE 5: MEETING WORKSPACE
───────────────────────────
Actor: Meeting Coordinator (P&D Organizer)
  │
  ├─ Schedule Pre-PDWP Meeting
  │    ├─ Link PC form to agenda subject
  │    ├─ Add participants, set date/time/location
  │    └─ One Pre-PDWP per scheme (unless defer-repeat flag)
  │
  ├─ Pre-PDWP Held → Save MoM → Collect co-signatures (2 required)
  │
  ├─ Schedule PDWP Meeting (requires Pre-PDWP per scheme)
  │    ├─ Link PC form to agenda
  │    └─ Add participants including co-signatories
  │
  ├─ PDWP Held → Save MoM → Collect co-signatures (4 required)
  │
  ├─ Generate/Edit Advice Letter per linked PC form
  │
  └─ [FORWARD FOR ADVICE TO CHAIRMAN]
       ├─ Creates forward_chairman review record
       ├─ Sets mws_advise_forwarded_at on meeting
       ├─ Status label → "Forwarded to Chairman"
       └─ Notification: pc_form_advice_forwarded_chairman → Chairman

PHASE 6: CHAIRMAN REVIEW
────────────────────────
Actor: Chairman
  │
  ├─ Receives notification → Opens PC Form Details modal or Meeting page
  ├─ Reviews: Working Paper, MoM, Advice Letter, full PC Form
  ├─ MoM signature gate must be complete
  │
  ├─ [APPROVE] → State: APPROVED
  │    ├─ Signature required
  │    ├─ Single approval may finalize (meeting path)
  │    └─ Notification: pc_form_approved → All participants
  │    └─ → GO TO PHASE 8
  │
  └─ [DEFER] → State: Deferred (Modified on resubmit)
       └─ → GO TO PHASE 7

PHASE 7: DEFERRED / RESUBMISSION
─────────────────────────────────
Actor: Creator/Submitter
  │
  ├─ Receives defer notification with remarks
  ├─ Opens Details modal → Reads deferral history
  ├─ Clicks Edit → Wizard opens with full edit access
  ├─ Makes corrections per reviewer remarks
  ├─ [SAVE DRAFT] → Optional intermediate save
  │
  └─ [RESUBMIT] → State: Forwarded for Checking
       ├─ Review counters reset to zero
       ├─ New submission cycle begins
       ├─ is_modified = true (if deferred at P&D/Chairman stage)
       ├─ Modified badge displayed on row
       └─ → GO TO PHASE 2 (full re-review from Checker)

PHASE 7b: POST-APPROVAL REVISION (REVISED)
───────────────────────────────────────────
Actor: Creator/Submitter (from Approved PC-I)
  │
  ├─ Opens approved PC-I → Begin Revised PC
  ├─ System creates post-approval revision workspace (editable shell)
  ├─ Submitter edits → Submits
  ├─ New row created: is_revised = true, parent_id set
  ├─ Old approved row: status = false (superseded)
  │
  └─ [RESUBMIT] → State: Forwarded for Checking
       └─ → GO TO PHASE 2 (full re-review from Checker)

PHASE 8: APPROVED (TERMINAL)
─────────────────────────────
  │
  ├─ State: approved, status: true
  ├─ Form is read-only
  ├─ Cover page shows APPROVED status
  ├─ All participants notified
  ├─ External webhook may fire (BPMS integration)
  │
  ├─ Approved PC-I unlocks PC-III eligibility on scheme
  ├─ Approved PC-IV unlocks PC-V eligibility on scheme
  │
  └─ [OPTIONAL] Begin Revised PC → GO TO PHASE 7b

PHASE 9: SUPERSEDED / INACTIVE
───────────────────────────────
  │
  ├─ Triggered when: Revision submitted, workspace abandoned
  ├─ status = false (hidden from active listings)
  ├─ Retained in database for audit and revision chain
  └─ Revision chain: parent_id → rootPcFormId() → version number

═══════════════════════════════════════════════════════════════════
                    END OF WORKFLOW
═══════════════════════════════════════════════════════════════════
```

## Document Metadata

| Attribute | Value |
|---|---|
| **System** | Sindh Development Portfolio Management System (PMS) |
| **Module** | Planning & Development PC Form Management |
| **PC Form Types** | PC-I, PC-II, PC-III(A), PC-III(B), PC-IV, PC-V |
| **Workflow Stages** | Draft → Checker → Department → P&D → Meeting → Chairman → Approved/Deferred |
| **Actors** | 10 defined actor types |
| **Business Rules** | 65 documented rules |
| **Scenarios** | 5 complete end-to-end scenarios |
| **States** | 12 defined states/labels |
| **Excluded** | MEC workflows, visit plans, M&E reports |

This document is suitable as the source specification for generating BPMN diagrams, UML Activity Diagrams, Mermaid flowcharts, or enterprise architecture diagrams. All workflows, decision points, actors, states, and module interactions are described in sufficient detail for automated or manual diagram generation.