MOC Lifecycle

This page provides a detailed walkthrough of the complete MOC lifecycle, covering every state transition, the code paths involved, and how the frontend and backend interact at each stage.

State Machine

A MOC progresses through the following states:

                    ┌──── decline ◀── Implementer (B)
                    │                     │
                    │                     ▼
  Originator (A) ──┤              HSEQ Review (C)
  status: "a"      │                 │        │
                    │          return │        │ approve
                    │          to "b" │        ▼
                    │                 │   Approver (D)
                    │                 │     │       │
                    │                 │  decline   approve
                    │                 │     │       │
                    │                 │     ▼       ▼
                    │                 │  decline  Implementation (E)
                    │                 │              │         │
                    │                 │       deviation/     complete
                    │                 │       extension       │
                    │                 │          │            ▼
                    │                 └──────────┘     Verification (F)
                    │                                       │
                    │                                    close out
                    │                                       │
                    └── decline ◀── Approver (D)        completed

Step-by-Step Walkthrough

1. MOC Creation (Status: a → b)

User action: A user navigates to Initiate MOC and fills out the originator form.

Frontend path:

• Page: src/app/dashboard/Moc/create/page.tsx
• Form: src/components/forms/mocForms/originatorForm.tsx
• The form collects: description, reason for change, department, affected departments/vessels, implementer selection, and attachments

API call: POST /api/newmoc

Backend flow:

1. Reads user identity from JWT cookie
2. Counts existing MOCs to generate serial number
3. Creates an originator form document (Mongoose model: originator)
4. Creates a chat room document (Mongoose model: chat)
5. Creates the MOC document with all references and status: "b"
6. Sends email notification to the assigned implementer

After creation: The MOC appears in the implementer's tracking view with status "Pending — Assessment".

2. Implementer Assessment (Status: b → c or decline)

User action: The implementer opens the MOC from their tracking view and fills out the assessment form (Part B).

Frontend path:

• Page: src/app/dashboard/Moc/list/[moc_id]/page.tsx (Step 1)
• Form: src/components/forms/formComponents/implementerFormTable.tsx
• The form collects ~20 fields including change assessment answers, category, timeline, approver/HSEQ assignment

Additionally during this stage:

• Impact assessment: src/components/impactAssessment/ → POST /api/impact
• Risk assessment upload: → POST /api/risk_assessment
• Action plan: → POST /api/actionTable
• Manuals plan: → POST /api/manualsPlan

API call: POST /api/submit/implementer

Backend flow (approval):

1. Verifies the user is the assigned implementer
2. Creates/updates the implementer form document
3. Sets MOC status: "c"
4. Adds HSEQ and Approver users to all_users
5. Sends emails to HSEQ (department and individual), approver, and all MOC users

Backend flow (decline):

1. Detects "details-assessed = no" or "necessary-justified = no"
2. Creates a decline record with stage "b" and the reason
3. Sets MOC status: "decline"
4. Sends decline emails to originator and all users

3. HSEQ Review (Status: c → d or back to b)

User action: The HSEQ reviewer opens the MOC and answers the three review questions.

Frontend path:

• Page: src/app/dashboard/Moc/list/[moc_id]/page.tsx (Step 2)
• Form: src/components/forms/formComponents/hseqForm.tsx

API call: POST /api/submit/hseq

Backend flow (approval): All three answers are "yes" → MOC advances to status: "d".

Backend flow (return): Any answer is "no" → MOC returns to status: "b" for the implementer to revise. This is a return, not a decline — the MOC can still proceed.

4. Approver Review (Status: d → e or decline)

User action: The approver reviews all submitted forms and makes their decision.

Frontend path:

• Page: src/app/dashboard/Moc/list/[moc_id]/page.tsx (Step 3)
• Form: src/components/forms/formComponents/approver.tsx

API call: POST /api/submit/approver

Backend flow (approval): MOC advances to status: "e".

Backend flow (decline): approver-moc-approved === "no" → MOC set to status: "decline".

5. Implementation (Status: e → f or back to b)

User action: The implementer fills out the implementation form documenting execution.

Frontend path:

• Page: src/app/dashboard/Moc/list/[moc_id]/page.tsx (Step 4)
• Form: src/components/forms/formComponents/implementation.tsx

API call: POST /api/submit/implementation

Standard completion: No deviations or extensions → MOC advances to status: "f".

Deviation/Extension path:

1. If deviation or extension is flagged, MOC returns to status: "b"
2. An extentionsAndDeviations object is created on the MOC
3. The implementer (or other authorized users) must resolve each deviation/extension via POST /api/submit/deviation-extention
4. Once resolved, MOC advances to status: "f"

6. Verification and Close-out (Status: f → completed)

User action: The HSEQ/Verifier user confirms all implementation items are complete and closes the MOC.

Frontend path:

• Page: src/app/dashboard/Moc/list/[moc_id]/page.tsx (Step 5)
• Form: src/components/forms/formComponents/verification.tsx

API call: POST /api/submit/verifier

Backend flow:

1. Creates/updates the verifier form document
2. Sets status: "f" and completed: true
3. Sends completion emails to all stakeholders

Audit Logging

Every form submission pushes an audit log entry to the MOC's logs array:

{
  userId: ObjectId,
  action: "created originator form" | "updated implementer form" | ...,
  timestamp: Date
}

The logs are displayed in the MOC tracking card's expandable details section via MocCardLogs.tsx.

Role-Based Form Access

The MOC detail page determines which forms are editable vs. read-only based on the current user and MOC status. This logic is in the previewOrEdit() function at src/app/dashboard/Moc/list/[moc_id]/page.tsx:

User Role	Status	Editable Forms
Originator	a	Part A only
Implementer	b	Parts A (read), B (edit)
HSEQ	c	Parts A-B (read), C (edit)
Approver	d	Parts A-C (read), D (edit)
Implementer	e	Parts A-D (read), E (edit)
HSEQ/Verifier	f	Parts A-E (read), F (edit)