System Overview
Auth & Tenant Flow
Sample Management
Equipment Calibration
Quality Walkabout
Pest Control
Blue Cards
Checklists
Request Lifecycle
Frontend Layer
🌐
Web Browser
index.html / login.html
Vanilla JS
→
⚡
Express Server
server.js · port 3456
Node.js
→
🗄️
MariaDB
qcsample database
10 conn pool
→
🔴
Redis
Session storage
Prod only
Middleware Stack
🗜️
Compression
gzip responses
→
🔐
Session MW
Redis / memory
→
🏢
Tenant Detection
domain → company_id
→
🛡️
Auth Check
requireAuth()
→
🔑
Module Access
view / edit / none
→
🔍
Access Filter
getAccessControlFilter()
Feature Modules
🧪
Sample Management
Batch, storage, transactions
Module
⚙️
Equipment Calibration
Certificates, scheduling
Module
🚶
Quality Walkabout
Observations, CAPA, closure
Module
🐛
Pest Control
Devices, readings, meetings
Module
🟦
Blue Cards
Improvement cards, workflow, savings
Module
✅
Checklists
Templates, runs, evidence, PDF
Module
System Services
📧
Email (Nodemailer)
OTP, password reset
📎
File Uploads (Multer)
PDF, image, Excel
📄
QCPdfEngine
A4 PDF exports
🖨️
Label Printer
ESC/POS · Zebra ZD230
💾
Auto Backup
mysqldump · rotate 10
Login Entry Point
👤
User Enters Email
login.html form
→
🔎
Tenant Domain Check
/api/tenant/check
→
❓
OIDC Configured?
tenant_auth_config lookup
Local Authentication Path
🔏
Password Entry
auth_type = local
→
🔒
bcrypt Verify
POST /api/login
→
📋
Load User + Modules
user_module_access
→
✅
Session Created
→ index.html
OIDC SSO Path (Okta / Azure AD / Google)
🔗
Initiate OIDC Login
GET /auth/login
→
📡
Discovery Fetch
1h TTL cache
→
🎲
State + Nonce
CSRF protection
→
🏛️
Identity Provider
Okta / Azure / Google
→
↩️
OIDC Callback
GET /auth/callback
→
👤
User Lookup / Create
external_identities
→
✅
Session Created
→ index.html
Access Control Levels
👑
Master Admin
Level 1 — all data
🏢
Company / Country Admin
Level 2–3
🏭
State / Plant Admin
Level 4–5
👷
Regular User / Coord
Level 7–9
Password Reset Flow
📧
Forgot Password
POST /api/forgot-password
→
🔢
Generate OTP
5-min expiry, email sent
→
✔️
Verify OTP
POST /api/verify-otp
→
🔑
Reset Password
bcrypt hash stored
Storage Hierarchy
🏭
Plant
plants table
→
🗃️
Rack
racks table
→
📦
Bin
bins table
→
🧪
Sample (Batch)
samples table
Sample Lifecycle
Create
➕
New Sample Form
batchID + dates + bin
→
✔️
Validate Bin + Scope
Access control check
→
💾
Store in DB
samples table
Check-Out
📤
Take Out Sample
/api/transactions/takeout
→
📝
Log Transaction
transactions table
→
🔓
Sample Out
Status updated
Return
📥
Return Sample
/api/transactions/return
→
📝
Log Return
transactions table
→
🔒
Sample Returned
Bin restored
Transfer
↔️
Transfer Request
/api/samples/transfer
→
✔️
Validate Destination
Capacity check
→
💾
Update Location
samples.bin_id updated
Expiry
📅
Update Expiry
/api/samples/update-expiry
→
📋
Audit Trail
expiry_updates table
→
✅
Expiry Updated
Audit logged
Equipment Registration
➕
Add Equipment
Manual or Excel bulk
→
📅
Calculate Next Date
calibrationDate + intervalDays
→
🗄️
equipment_calibrations
Full equipment record
Certificate Upload
📎
Upload PDF Certificate
PDF only · 10MB max
→
✔️
Multer Validates
Type + size check
→
🔄
1-per-equipment Rule
Replace old doc
→
💾
calibration_documents
Path + metadata stored
Calibration Update Tracking
📝
Log Calibration Update
Before/after values
→
🔄
Store Update
calibration_updates table
→
📅
Next Date Recalculated
History preserved
Export & Reporting
📊
Export Request
GET /api/.../export
→
🔍
Filter + Query
Access-scoped
→
📥
Excel / PDF Export
XLSX or A4 PDF
Observation Lifecycle
Report
👁️
Raise Observation
Draft created
→
📝
Save as Draft
status = Draft
→
📎
Attach Evidence
PDF/Image · 5MB
Submit
📤
Submit Observation
Draft → Open
→
👷
Assign Action Person
Responsibility set
→
📋
History Entry
quality_walkabout_history
Action
🔧
CAPA Details
Corrective + Preventive
→
💬
Add Comments
Discussion thread
→
📎
Action Evidence
Separate attachment set
Close
🔐
Closure Request
Authority check required
→
❓
Authorized?
closure_authority table
→
✅
Closed
status = Closed
Reopen
🔄
Reopen Observation
reopenCount++
→
📝
Status → Open Again
repeatFlag tracked
Device Registry
🪤
Pest Devices
4 types · 2 placements
→
🗺️
Layout Maps
pest_layout_images
→
🧴
Chemical Master
Dosage defaults
Monitoring Readings
🦟
Insect Readings
Count + species breakdown
Fortnightly
🐭
Rodent Checks
Status codes B/R/O/D/NA
Monthly
🕷️
Spider Checks
Status B/R/NA
Monthly
Pest Control Activities
💨
Spray Tracking
Chemical + dosage log
🦎
Lizard Service
Quarterly IPM
📅
Annual Control Plan
Monthly activity matrix
Meetings & Action Items
Meeting
📋
Schedule Meeting
Monthly / Quarterly / Special
→
👥
Record Attendees + MOM
Minutes of Meeting
→
💾
pest_meetings
Full meeting record
Actions
⚡
Raise Action Items
From meeting discussion
→
🔄
Track Status
open → progress → closed
→
💾
pest_action_items
Full action record + MOM
Documents & Audit
📄
Version-Controlled Docs
1-per-category PDFs
👷
Control Team
pest_control_team
📋
Activity Audit Log
pest_activity_log
📊
Reports + Heatmaps
Trends · Export
Every API Request — Step by Step
🌐
Browser Request
fetch /api/* + cookies
→
🗜️
Compress + Parse
gzip · JSON body
→
🔐
Session Load
req.session attached
→
🏢
Tenant Detect
domain → company_id
→
🛡️
Authenticated?
requireAuth()
🔑
Module Access?
samples/calib/pest/walk
→
🔍
Build Access Filter
SQL WHERE clause
→
🗄️
Parameterized Query
MariaDB pool · no injection
→
🔄
Transform Result
Format + nulls handled
→
📤
JSON Response
Compressed + sent
Write Operation (Create / Update / Delete)
✏️
Write Request
POST / PUT / DELETE
→
✔️
Edit Permission
view ≠ edit
→
🔒
Inject Tenant Scope
company_id from session
→
🗄️
Execute SQL
Pool connection + release
→
📋
Audit Log
History table write
→
✅
Success Response
200 / 201 / 204
Session User Object (req.session.user)
👤
Identity
id, email, role, auth_type
🏢
Hierarchy
company → plant → dept
🔑
Module Access
edit / view / none per module
Raise Card
🟦
Raise Blue Card
POST /api/blue-cards
→
🆕
Status = OPEN
Plant-scoped submitter
→
🗄️
blue_cards
Full card record
Status Workflow
🔵
OPEN
Awaiting review
→
👀
ACKNOWLEDGED
PATCH .../status
→
🔧
IN_PROGRESS
Action underway
→
🏁
IMPLEMENTED / REJECTED
Terminal states
Savings & Analytics
💰
Log Savings
savings_amount on card
→
📊
Aggregate Analytics
GET .../analytics
→
📥
Dashboard + Export
Charts, Excel/PDF
Author (Template Designer)
📝
Build Template
Sections, questions, rules
→
💾
Save Draft
POST .../templates
→
🚀
Publish
Immutable version snapshot
→
🗄️
checklist_templates /
checklist_versions
Template + version history
Execute (Run)
📋
Pick Checklist
GET .../available
→
▶️
Start Run
Freezes version snapshot
→
📷
Answer + Photo Evidence
Mobile sectioned form
→
⚖️
Rules Engine Validates
Fail → overall FAIL
→
✅
Submit
POST .../submit
→
🗄️
checklist_runs /
responses / attachments
Run + answers + photos
Analyze
📊
Checklist Runs Dashboard
GET /api/checklists/runs
→
🔍
Apply Filters
Template, plant, status, date
→
📄
PDF Export
QCPdfEngine · A4
Trigger / Entry
Processing Step
Tool / Service
Output / Result
Data Store
Decision Point