PowerGridPro

⚙️

Admin Setup

Platform initialization by Super Admin — one-time setup

Phase 1

Step 1

🏢

Create Tenant

Register the company as a new tenant with complete data isolation.

Details

What happens

A unique tenant_id (UUID) is generated for the company
Every database table has a tenant_id column — all queries are filtered by it
Company A can never see Company B's projects, employees, or financial data
Tenant gets a unique key, name, and is_active flag
Soft delete supported — deactivated tenants retain data but lose access

API Endpoints

POST /api/admin/tenants GET /api/admin/tenants PUT /api/admin/tenants/:id

Step 2

💳

Subscribe to Plan

Choose Basic, Pro, or Enterprise. Includes trial, auto-renewal, and usage limits.

Details

Subscription Features

Plans: Basic, Pro, Enterprise — monthly or yearly billing
Trial: Configurable trial period with automatic expiration
States: Trial → Active → Past Due → Grace Period → Expired → Cancelled
Usage limits: Max projects, users, storage — enforced per plan
Feature flags: Each plan enables specific features (e.g., AI Copilot = Enterprise only)
Module access: Plans control which modules are available
Auto-renewal: Automatic billing with payment gateway integration
Audit log: Every subscription change is logged

API Endpoints

GET /api/subscription POST /api/subscription/upgrade POST /api/subscription/cancel GET /api/v1/subscription/summary

Step 3

🧩

Enable Modules

Turn on/off modules: Projects, HR, Safety, Equipment, Inventory, Analytics.

Details

Available Modules

Operations: Projects, Safety, Equipment, Drawings, Milestones, Schedule, Teams
HR: Employees, Teams, Attendance, Payroll, Resources
Inventory: Inventory Dashboard, Materials, Expenses
Admin: User Management, RBAC, Subscription, Module Control, Tenant Settings
Analytics: Dashboards, Reports, Charts, KPIs, Trends
Each module can be independently enabled/disabled per tenant
Sidebar navigation auto-hides disabled modules

API Endpoints

GET /api/modules PUT /api/modules GET /api/nav/sidebar-tree

Step 4

🎨

Tenant Settings

Configure company branding, currency, date format, timezone.

Details

Configuration Options

Branding: Company logo (uploaded via /uploads/logos/), company name
Currency: USD, EUR, AUD, INR, etc. — affects all monetary displays
Date format: MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD
Timezone: Used for all date/time calculations
System data templates: Pre-configured lookup data (categories, statuses, types)
Custom pipes (TenantCurrencyPipe, TenantDatePipe) format data per tenant settings

API Endpoints

GET /api/tenant-settings PUT /api/tenant-settings

👥

Company Onboarding

Set up workforce, roles, equipment, and inventory before starting projects

Phase 2

Step 1

👤

Create Users & Employees

Add employee profiles and create login accounts for staff who need system access.

Details

Employee Data

Identity: Employee ID, name, email, phone, profile photo
Personal: Date of birth, gender, structured address
Work: Designation, department, site assigned, employment type (full-time/part-time/contract)
Hierarchy: Manager ID for reporting structure
Emergency contacts: Name, relationship, phone
Documents: Upload and verify certifications, licenses, ID documents
Status tracking: Active, on leave, inactive with date tracking

User Accounts

Not all employees need user accounts — only those who log into the system
User accounts linked to employees via user_id
JWT authentication with access + refresh tokens

API Endpoints

GET/POST /api/employees POST /api/auth/register GET/POST /api/teams

Step 2

🔐

Define Roles & Permissions

Create roles (PM, Foreman, Accountant) with granular permission control.

Details

RBAC System

Roles: Custom per tenant — Project Manager, Foreman, Safety Officer, Accountant, Admin
Permissions: Granular format: entity.action (e.g., employees.read, payroll.smart.generate)
Categories: CRUD, Smart Actions, Admin, Report permissions
Risk levels: Each permission classified as low/medium/high/critical
Multi-role: Users can have multiple roles — permissions are combined (union)
Temporary access: Role assignments can have expiration dates
Wildcards: Support entity.* and *.* patterns
Row-level security: Optional conditions on role-permission mappings (JSONB)
System roles: admin, super_admin are protected and cannot be deleted

API Endpoints

GET/POST /api/rbac/roles POST /api/rbac/roles/:id/permissions POST /api/rbac/users/:id/roles

Step 3

🚜

Register Equipment

Add all tools, vehicles, and heavy equipment with full lifecycle tracking.

Details

Equipment Tracking

Identification: Equipment code, barcode, QR code, asset tag, serial number
Categories: Vehicles, power tools, heavy machinery, safety equipment, electrical tools
Lifecycle: Purchase date, price, warranty expiry, depreciation
Maintenance: Preventive schedules based on meter readings (hours, km, miles, cycles)
Fleet: License plate, VIN, fuel type, mileage, insurance expiry
Assignment: Track who has what equipment, on which project
Compliance: Inspection certifications, calibration dates
Condition: Track condition at assignment and return

API Endpoints

GET/POST /api/equipment POST /api/equipment/:id/assign POST /api/equipment/:id/return GET /api/equipment/needs-maintenance GET /api/equipment/stats

Step 4

📦

Setup Inventory & Suppliers

Add materials with SKU/pricing/stock levels. Register suppliers with payment terms.

Details

Inventory Management

Items: SKU, barcode, brand, model number, serial/batch/lot numbers
Stock: Quantity, min/max/safety stock levels, automatic low-stock alerts
Pricing: Unit price, average cost, last purchase price, selling price, tax rate
Location: Multi-warehouse with bin/zone/rack/level positions
Transactions: Every movement logged — in, out, adjustment, return, transfer
Compliance: Hazmat class, storage conditions, certifications
Expiry: Shelf life and expiration tracking

Supplier Management

Vendor master with GST/PAN, contact info, payment terms
Bank details for payment processing
Lead time tracking for procurement planning

API Endpoints

GET/POST /api/inventory GET /api/inventory/low-stock GET/POST /api/inventory/suppliers GET/POST /api/inventory/transactions

📋

Project Lifecycle

Project → Phases → Milestones → Approve → Assign Resources → Create Tasks

Phase 3

Step 1

🏗️

Create Project

Enter client, contract, location, budget, risk level. Assign PM, Superintendent, Foreman.

Details

Project Data

Identity: Project code, name, type (residential/commercial/industrial/infrastructure), priority, category
Client: Client name, contact person, email, phone, billing address
Contract: Number, type (fixed price/cost plus/time & materials/unit price), value, payment terms, tax rate, retainage %
Location: Full address, GPS coordinates, timezone, site conditions, access instructions
Budget: Total budget, estimated cost, start/end dates
Team: Manager, Superintendent, Foreman, Owner — all linked by user ID
Risk/Safety: Risk level, safety level, insurance details, permits
Status flow: Planning → Active → On Hold → Completed → Cancelled

API Endpoints

GET/POST /api/projects GET/PUT/DELETE /api/projects/:id GET /api/projects/stats

Step 2

📐

Define Phases

Break project into phases, each with its own budget allocation and date range.

Details

Phase Structure

Examples: Site Prep, Foundation, Framing, Electrical Rough-In, Plumbing, HVAC, Drywall, Finishing
Each phase has: phase_code, name, description, start_date, end_date
Budget allocation per phase — tracked separately from project total
Phase ordering with drag-and-drop reorder
Phase utilization analysis — compare planned vs actual hours and costs
Phases contain milestones, which contain tasks — this is the WBS hierarchy

API Endpoints

GET/POST /api/projects/:id/phases GET /api/projects/:id/phase-utilization

Step 3

🎯

Create Milestones

Set milestones per phase with budget, dates, and deliverables. Assign equipment & materials.

Details

Milestone Data

Core: Milestone code, name, description, phase link
Budget: Allocated budget, actual costs tracked via cost entries
Schedule: Start date, end date, weight (for progress calculation)
Resources: assigned_equipment (JSONB array of UUIDs), assigned_materials (JSONB array of UUIDs)
Progress: Percentage complete, auto-calculated from tasks or manually set
Status flow: Pending → Approved → In Progress → Completed → Overdue

Resource Assignment

Admin assigns specific equipment IDs and material IDs to each milestone
This scopes what's available when creating tasks under this milestone
Prevents workers from booking equipment meant for another phase

API Endpoints

GET/POST /api/projects/:id/milestones PUT /api/milestones/:id/resources GET /api/milestones/:id/resources

Step 4 — Approval Gate
✅
Approve Milestone
Supervisor approves. Only approved milestones appear in task form. Prevents unauthorized work.
Details
Approval Workflow
Why: Ensures no work starts until the milestone is reviewed for scope, budget, and resource allocation
Who: Project Manager or Supervisor with approval permissions
UI: Amber "Approve" button shown for pending/in_progress milestones
After approval: Green "Approved" badge appears, milestone shows in task creation dropdown
Impact: Task form filters milestones to status === 'approved' only
Toast notification: Success/error toast on approve action
Audit: updated_by tracks who approved and when
API Endpoints

          POST /api/milestones/:id/approve
        

After Milestone Approval — Task Creation

Step 5

📝

Create Tasks

Create tasks under approved milestones. Resources are scoped to the selected milestone.

Details

Task Form Sections

Basic Info: WBS code (auto or manual), name, category (electrical/plumbing/HVAC/concrete/etc.), priority
Hierarchy: Parent task (searchable dropdown of ALL tasks), milestone (approved only), phase (auto-populated)
Schedule: Planned hours, start date, end date, duration auto-calculated
Assignment: Team (searchable), employees from team (multi-select, saved as UUIDs)
Resources: Equipment & materials — dropdowns scoped to milestone's assigned resources
Cost: Cost estimate, labor hours (visible only to users with cost permissions)

Resource Scoping Logic

When milestone is selected → API fetches that milestone's assigned_equipment and assigned_materials
Equipment/material dropdowns only show those items
When milestone is cleared → all equipment and materials reload
When editing existing task with milestone_id → resources auto-load on form open

API Endpoints

POST /api/schedule-tasks PUT /api/schedule-tasks/:id GET /api/milestones/:id/resources

Step 6

👷

Assign Team & Crew

Assign a team and individual employees by UUID. Track exactly who does what.

Details

Assignment Flow

Search and select a team — loads team members automatically
Pick individual employees from team members or all employees
assigned_to stored as JSONB array of employee UUIDs (not names)
assigned_team stores team name, assigned_team_id stores team UUID
Backend tracks both for reporting and filtering

Step 7

📅

Set Schedule & Gantt

Set dates, planned hours, duration. View on interactive Gantt chart.

Details

Schedule Features

Gantt chart: Interactive timeline with horizontal bars per task
WBS hierarchy: Parent/child tasks shown with expand/collapse
Color coding: Tasks colored by status, priority, or custom color
Drag-and-drop: Reorder tasks in the schedule
Constraint types: As Soon As Possible, Start No Earlier Than, etc.
Duration: Auto-calculated from start/end dates

Step 8

🔗

Add Dependencies

Link tasks with FS/SS/FF/SF relationships. Critical path auto-calculates.

Details

Dependency Types

Finish-to-Start (FS): Task B starts after Task A finishes (most common)
Start-to-Start (SS): Task B starts when Task A starts
Finish-to-Finish (FF): Task B finishes when Task A finishes
Start-to-Finish (SF): Task B finishes when Task A starts
Lag time: Configurable delay between linked tasks
Critical path: System auto-identifies tasks that cannot slip without delaying the project
Float/slack: Shows how much each task can slip
Dependencies stored as JSONB array: [{task_id, type, lag}]

🔨

Daily Execution

Field crew daily activities — time, costs, safety, and documentation

Phase 4

Core Daily Activities

Morning

📍

Crew Check-In

Attendance with geolocation. Records check-in time, location, and project site.

Details

Daily attendance record per employee with check-in/out timestamps
Geolocation captured to verify employee is at the correct project site
Feeds into payroll calculations (hours worked × rate)
Overtime tracking — hours beyond standard work day
Leave and absence tracking integrated

GET/POST /api/attendance

Ongoing

⏱️

Log Time Entries

Workers log hours per task — labor, supervision, overtime. Links to cost tracking.

Details

Time entries linked to specific milestone + task
Entry types: labor, supervision, overtime, travel
Hourly rate applied for cost calculation
Approval workflow: submitted → approved/rejected
Hours roll-up view: by employee, by task, by project
Feeds into EVM (Earned Value) calculations

GET/POST /api/milestones/:id/time-entries POST /api/time-entries/:id/approve

Ongoing

💰

Track Costs

Record costs by category: labor, materials, equipment, subcontractor, overhead.

Details

Cost entries per milestone with category breakdown
Each entry: amount, description, vendor, cost code, receipt attachment
Approval workflow: pending → approved → posted
Cost history with full audit trail — who created/approved/modified
Cost snapshots for trend analysis over time
Cost flow timeline showing daily totals + cumulative

GET/POST /api/milestones/:id/cost-entries POST /api/cost-entries/:id/approve GET /api/projects/:id/cost-history

Ongoing

📊

Update Task Progress

Update % complete. Auto-calculates from actual vs planned hours. Gantt updates live.

Details

Percent complete: auto-calculated (actual_hours / planned_hours) or manually set
Task status flow: Not Started → In Progress → Completed → On Hold
Actual start/end dates recorded separately from planned
Milestone progress aggregates from child task progress
Phase progress aggregates from milestone progress
Project percent_complete rolls up from all phases

PUT /api/schedule-tasks/:id POST /api/milestones/:id/progress

Safety & Documentation

📓

Daily Log

Record site notes, weather, workforce count, deliveries, and issues.

Details

Date, weather conditions, temperature, workforce count
Work performed summary, equipment used
Deliveries received, visitors on site
Issues, delays, and safety observations
Linked to project for historical record

🦺

Safety Inspection

Digital checklists with scoring, findings, photos, and signatures.

Details

Templates: Reusable checklist templates (PPE, scaffolding, electrical, fire, excavation)
Scoring: Each item scored — total score, max score, pass/fail threshold
Findings: Non-conformances with severity and corrective actions
Context: Weather conditions, number of workers, safety officer present
Signatures: Digital inspector and reviewer sign-off (JSONB)
Photos: Attach evidence photos to findings
Schedule: Recurring inspection schedules with auto-generation
Workflow: Draft → Scheduled → In Progress → Completed → Reviewed

GET/POST /api/safety/inspections POST /api/safety/inspections/:id/complete GET /api/safety/checklist-templates

🌦️

Weather Check

Forecast, alerts, and impact analysis for construction scheduling.

Details

Widget: Current conditions on project dashboard
Forecast: Multi-day forecast for planning
Alerts: Severe weather warnings (high winds, storms, extreme heat)
Impact analysis: How weather affects schedule and what to do
Instructions: "Secure scaffolding and loose materials before 11 AM"
Feeds into daily logs and safety inspections

📸

Photo & Documents

Progress photos in albums. Documents with version control and tag search.

Details

Photos: Organized in albums, linked to projects/tasks/inspections
Documents: Central repository with folder hierarchy
Versioning: Track file versions with parent-child relationships
Drawings: Drawing sets with revision control and distribution tracking
Acknowledgment: Recipients confirm receipt of drawings
Security: Virus scan status, checksum, retention policies
Tags: JSONB tags for search and categorization

GET/POST /api/files GET/POST /api/projects/:id/documents GET/POST /api/drawing-sets

When Issues Arise

🚨

Incident Report

Report injuries, property damage, near misses. Full OSHA-grade investigation.

Details

Types: Injury, property damage, environmental, near miss, equipment failure
Severity: Minor, moderate, serious, critical, fatal
Injury details: Person, type, body part, treatment, hospital, days lost
Location: Site area, zone/floor, GPS coordinates
Investigation: Root cause, immediate cause, contributing factors
Witnesses: JSONB array of witness statements
CAPA: Corrective and preventive actions with due dates
Workflow: Draft → Reported → Under Investigation → Resolved → Closed

GET/POST /api/safety POST /api/safety/:id/resolve GET /api/safety/stats

❓

Submit RFI

Request for Information when design clarification needed.

Details

Formal question to architect/engineer when drawings are unclear
Track response time and schedule impact
Link to specific drawings and project areas
Status tracking: open → answered → closed

📎

Submittal & Change Orders

Submit materials/shop drawings for approval. Manage scope changes.

Details

Submittals: Material samples, shop drawings, product data for approval
Change Orders: Scope changes with cost and schedule impact analysis
Approval chains with review status tracking
Both affect project budget and timeline — tracked in cost system

📈

Management & Oversight

Dashboards, financial control, approvals, analytics, and AI insights

Phase 5

Schedule & Financial Control

📊

Gantt Chart

Interactive timeline with dependencies, critical path, and color-coded status.

Details

Visual bars for every task, color-coded by status or priority
Dependency arrows between linked tasks
Critical path highlighted in red — tasks that can't slip
WBS tree with expand/collapse for parent-child hierarchy
Today line marker, milestone diamonds
Drag-to-reschedule and reorder support

📉

Cost Variance Analysis

Budget vs actual by phase, milestone, and cost category with drill-down.

Details

Budget vs actual vs forecast — side-by-side comparison
Variance by category: labor, materials, equipment, subcontractor, overhead
Drill down: project → phase → milestone → cost code → line item
Favorable/unfavorable variance with explanations
Cost variance matrix component for visual analysis

GET /api/projects/:id/cost-tracking/budget-vs-actual GET /api/projects/:id/comprehensive-costs

📐

Earned Value (EVM)

CPI, SPI, EAC, ETC — know if you're over budget or behind schedule.

Details

CPI (Cost Performance Index): Earned Value / Actual Cost — >1 = under budget
SPI (Schedule Performance Index): Earned Value / Planned Value — >1 = ahead of schedule
EAC (Estimate at Completion): Total predicted cost based on current performance
ETC (Estimate to Complete): Cost remaining to finish
Planned Value: What should have been spent by now
Earned Value: Value of work actually completed
All stored in Budget model and calculated dynamically

GET /api/projects/:id/cost-tracking/dashboard GET /api/projects/:id/cost-tracking/forecast

💵

Cash Flow Forecast

Weekly/monthly projections of money in vs out. Plan cash needs.

Details

Period types: weekly, monthly, quarterly
Inflows: Invoiced amount, received amount, expected receipts
Outflows: Labor, material, equipment, subcontractor, overhead costs
Net cash flow = inflows − outflows per period
Cumulative cash flow chart — predict when cash runs low
Actual vs forecast comparison

Approvals & Vendor Management

⭐

Vendor Performance

Rate vendors on quality, timeliness, cost. Track contracts and payments.

Details

Assign vendors to projects with contract terms and scope
Performance ratings: quality, schedule adherence, cost, safety, communication
Vendor cost breakdown and metrics per project
Invoice management with multi-level approval workflow
Payment tracking: pending, partial, paid

GET/POST /api/projects/:id/vendors POST /api/projects/:id/invoices/:id/approve

📝

Change Orders

Scope changes with cost/schedule impact. Nothing changes without sign-off.

Details

Change order reason, description, cost impact, schedule impact
Approval workflow with multi-level sign-off
Approved changes update the contract value and budget
History tracked for dispute resolution

🧾

Invoice Management

Progress billing with retainage. Submit, review, approve, track payment.

Details

Types: Progress, final, retainage, change order invoices
Amounts: Subtotal, tax, retainage hold, discount, total, balance due
Line items: Each linked to cost code for detailed tracking
Previous billing: Track cumulative billing vs current period
Status flow: Draft → Pending → Submitted → Approved → Paid
Days overdue tracking with aging reports

🦺

Safety KPIs

Incident trends, inspection scores, training completion. Spot problems early.

Details

Incident trend charts over time
Type breakdown: injuries vs near misses vs property damage
Inspection pass/fail rates and scores
Training completion rates and upcoming expiring certifications
Compliance record status dashboard
Safety statistics aggregated per project and company-wide

GET /api/safety/stats GET /api/safety/incident-trend GET /api/safety/inspections/statistics

Intelligence & AI

📊

Analytics Dashboard

Real-time KPIs across all projects. Custom reports with PDF/Excel/CSV export.

Details

Project health: on-track vs behind vs over budget
Workforce utilization: planned vs actual hours
Cost performance: CPI/SPI across all projects
Schedule adherence: tasks on time vs late
Custom report builder with configurable parameters
Export to PDF, Excel, CSV for client reporting
Portfolio view: compare multiple projects side by side
Trend analysis: historical performance over months/quarters

GET /api/ai-analytics/dashboard GET /api/ai-analytics/kpis GET /api/reports

🤖

AI Copilot

Chat interface, smart suggestions, predictive analytics, learning system.

Details

Chat: Natural language interface — ask questions about your projects
Intent recognition: Understands commands like "show me overdue tasks"
Smart suggestions: Context-aware recommendations based on project data
Automated actions: Execute routine tasks automatically
Predictions: Forecast cost overruns, schedule delays, safety risks
Anomaly detection: Flag unusual patterns (cost spike, late tasks clustering)
Learning: System improves with user feedback on suggestions
Enterprise only: Available on Enterprise subscription plan

POST /api/ai-copilot/chat GET /api/ai-copilot/suggestions POST /api/ai-copilot/feedback

🏁

Project Closeout

Punch list → Final inspection → Retainage release → Archive

Phase 6

Step 1

📋

Punch List

Create items for defects and incomplete work. Assign, track, and photograph resolution.

Details

Item description, location, responsible party, due date
Priority: critical, major, minor, cosmetic
Photo before/after for proof of resolution
Status: open → in progress → resolved → verified
All items must be cleared before final inspection

Step 2

🔍

Final Inspection

Run final quality and safety inspection. All punch items must be cleared.

Details

Final safety and quality checklist
Verify all punch items resolved
Generate inspection report with findings
Inspector and reviewer digital signatures
Certificate of completion

Step 3

💰

Retainage Release

Submit final invoice including held retainage. Process final payment.

Details

Final retainage invoice generated from held amounts
Client acceptance and sign-off required
Payment processing and reconciliation
Final cost report: budget vs actual vs contracted

Step 4

📁

Project Complete

Mark complete. Archive documents, drawings, photos. Generate final reports.

Details

Project status set to "completed"
All documents, drawings, and photos archived
Final cost report generated
Lessons learned recorded for future projects
Equipment returned and reassigned
Team members released back to resource pool
Data remains accessible for audits and reference

🔄

Always Running — Background Services

Security, sync, isolation, and audit active on every single request

Always On

🔑

JWT Auth & Silent Refresh

Access + refresh tokens. Silent refresh prevents random logouts.

Details

Access token (short-lived) for API requests
Refresh token (long-lived) for silent renewal
APP_INITIALIZER validates token on page load
If access token expires → automatic silent refresh
Only explicit 401/403 on refresh clears session
Network errors → keep session, user can retry
HTTP interceptor adds auth header to every request

🛡️

RBAC Permission Checks

Every request checks roles and permissions. Granular access control.

Details

@token_required decorator on every API endpoint
User roles checked against required permissions
Frontend hides UI elements based on permissions (e.g., cost fields)
Backend enforces — UI hiding is just convenience, not security

🏢

Tenant Isolation

Every query filtered by tenant_id. Complete company data separation.

Details

Every table has tenant_id column (UUID)
get_tenant_id() extracts from JWT token
check_tenant_access() validates on every query
Row-level isolation — not separate databases
Super admin can access all tenants for support

📝

Audit Trail

Every create, update, delete logged with who and when.

Details

created_at, created_by on every record
updated_at, updated_by tracked on every change
Soft deletes: is_active=false, deleted_at, deleted_by
Cost history: dedicated audit log for financial changes
Subscription audit log for plan changes
Safety inspection audit log for compliance

📱

Sync Engine & Offline

Delta sync, PWA service worker, Flutter mobile app for field workers.

Details

Device ID assigned to each browser/device
Delta sync: GET /api/v1/sync/pull?since=timestamp
Health check every 30 seconds: GET /api/v1/sync/health
Angular service worker for offline caching (production)
Flutter mobile app for inventory management on the go
Conflict resolution for concurrent edits

💳

Subscription Enforcement

Modules, features, and usage limits enforced per plan. Auto-trial expiration.

Details

Sidebar navigation filtered by subscription
API endpoints check subscription before processing
Usage counters (projects, users, storage) checked against limits
Grace period before full lockout on expiry
Upgrade prompts when limits are approached

Complete End-to-End Flow