← Back to App

Introduction

POD Governance is an internal workflow platform for managing delivery cycles, priorities & achievements (Priorities & Achievements), and team reporting. The platform implements a hierarchical approval chain: Project Lead → Project Manager → Delivery SPOC → Sales SPOC → POD Owner → Cluster Head. For Priorities & Achievements only, an optional Project Contributor tier sits below the Project Lead (Project Contributor → Project Lead → …); contributors are not shown in reports, Ups & Downs, or project membership.

App Shell

Every authenticated screen uses a unified left sidebar (dark navy, role-based navigation) plus a topbar with user avatar and notification bell. The shell is defined in AppShell.tsx.

Routing

Single-page application using React Router v6. Protected routes enforce authentication and role-based access. Admin routes additionally require the admin role.

Notifications

Email notifications use templates ET-001 → ET-022. In-app notification bell in topbar shows unread count with live polling. Clicking a notification navigates to the relevant screen.

Automation

Scheduler service runs 9 registered cron jobs (week kickoffs, reminders, digests, escalations, scheduled reports, Priorities & Achievements all-roles). Admins can inspect run history and trigger jobs manually.

Tech Stack

Frontend

  • React 18 + TypeScript
  • Vite build
  • React Router v6
  • Axios (API calls)
  • Recharts (charts in reports)

Backend

  • Node.js + Express
  • Prisma ORM
  • PostgreSQL database
  • JWT authentication
  • node-cron scheduler

Key Services

  • Notification service (email templates)
  • Scheduler service (9 cron jobs)
  • MCP server (stdio adapter) — 64 tools / 3 resources / 3 pre-built prompts
  • Audit log (all writes)
  • Scheduler run log

File locations

  • src/web/src/screens/ — React screens
  • src/api/src/ — API + services
  • src/api/prisma/ — schema + migrations

Roles & Access

Role keys stored in the database and JWT claims. Every user can hold multiple roles across different projects.

Role Key Display Name Workflow Screen Priorities & Achievements Chain Position
project_contributor Project Contributor Priorities & Achievements Screen (P&A only) Bottom tier — reports to Project Lead. Not shown in reports, Ups & Downs, or projects.
pl Project Lead Project Lead Screen Reports to Project Manager; also reviews their Project Contributors
pm Project Manager Project Manager Screen 2nd — reports to Delivery SPOC
delivery_spoc Delivery SPOC Delivery SPOC Screen 3rd — reports to Sales SPOC
sales_spoc Sales SPOC Sales SPOC Screen 4th — reports to POD Owner
pod_owner POD Owner POD Owner Screen 5th — reports to Cluster Head
cluster_head Cluster Head Cluster Head Screen 6th — top of chain
pmo PMO PMO Screen Observer/coordinator
admin Administrator Admin Portal Full access to all admin screens

Authentication

login screen

Login Screen

/login
All (unauthenticated)
  • Email + password authentication form with validation
  • 18 demo user tiles for quick one-click login (dev/staging)
  • OTP magic-link flow: server sends a verification email (ET-001)
  • Redirects authenticated users to /dashboard
  • "Forgot password" link triggers account activation flow
  • Demo users grouped by role (Project Lead, Project Manager, Delivery SPOC, Sales SPOC, POD Owner, Cluster Head, PMO, Admin)
verify screen

Email Verify Screen

/auth/verify
All (unauthenticated)
  • 6-digit OTP input for email verification (from ET-001 magic link)
  • Auto-submits when all 6 digits are entered
  • Resend code option with cooldown timer
  • On success: issues JWT and redirects to dashboard or intended route
  • Invalid / expired token shows inline error
activate screen

Activate Account Screen

/auth/activate
All (via invite link)
  • Password set form for first-time account activation
  • Requires invitation token from email link (ET-006)
  • Password strength indicator with real-time feedback
  • Confirm password field with match validation
  • On submit: activates account and auto-logs in the user

Navigation

dashboard screen

Module Picker (Dashboard)

/dashboard
All authenticated users
  • Landing page after login — shows role-relevant module tiles
  • Tiles rendered based on the user's roles (Workflow, Priorities & Achievements, Reports, Admin, Cycles)
  • Recent activity feed showing latest workflow events
  • Quick-access KPI cards: open submissions, pending reviews, overdue items
  • Notification bell with live unread count
  • Sidebar navigation always visible for direct module access
projects screen

Projects Screen

/projects
All authenticated users
  • Searchable, filterable list of all projects the user is associated with
  • Columns: project name, POD, status (active / inactive), assigned roles
  • Clicking a project navigates to the relevant workflow screen for that project
  • Status badges colour-coded (green = active, amber = pending, blue = on-hold)
  • Admin users see all projects; regular users see only their assigned projects

Workflow Screens

Each role in the delivery chain has a dedicated workflow screen. Screens share a common pattern: a header with cycle info, a KPI strip, a submission area, and a team-status table showing direct reports.

pl screen

Project Lead Screen

/workflow/pl
pl
  • Week KPI strip: current week ID, submission deadline countdown
  • Priorities text area — submit weekly priorities for the active cycle
  • Achievements text area — submit achievements from last week
  • Highlights / Lowlights free-text fields
  • Submit / Save Draft buttons; submitted state locks the form
  • Current Cycle / Next Cycle tabs — pre-plan the upcoming iteration's Ups & Downs as they happen; the next cycle is created (draft) on demand per the project cadence (weekly / biweekly / monthly)
  • Next-cycle submission window — Save as Draft anytime, but Submit to the Project Manager is disabled until one day before the cycle begins. The ET-001 "cycle started" kickoff still fires when the period actually starts
  • View submission history via link to cycle history
  • Automated ET-007 kickoff email triggers on Monday morning
pm screen

Project Manager Screen

/workflow/pm
pm
  • KPI strip: total Project Leads assigned, count submitted, count missing
  • Project Lead submissions table — view each Project Lead's priorities and achievements
  • Review each submission inline: approve, return with comment, or escalate
  • Own submission area for Project Manager's weekly Priorities & Achievements to Delivery SPOC
  • Missing submission follow-up action triggers ET-008 reminder email
  • Submission deadline indicator with colour change when overdue
del-spoc screen

Delivery SPOC Screen

/workflow/delivery-spoc
delivery_spoc
  • Aggregated view of all Project Manager rollup submissions
  • KPI strip: Project Manager count, reviewed vs pending
  • Expand each Project Manager row to see the full rollup detail
  • Add commentary and approve the Project Manager aggregation
  • Submit own rollup upward to Sales SPOC
  • ET-007 Priorities & Achievements kickoff can be sent via pa_kickoff_all scheduler job
sales-spoc screen

Sales SPOC Screen

/workflow/sales-spoc
sales_spoc
  • Receives Delivery SPOC rollups from direct reports
  • Review and approve each Delivery SPOC submission with comments
  • Consolidated summary view of delivery performance across SPOCs
  • Submit own synthesis upward to POD Owner
  • Deadline tracking and escalation path (ET-011)
pod screen

POD Owner Screen

/workflow/pod-owner
pod_owner
  • Rollup view from all Sales SPOCs within the POD
  • Progress stepper showing chain completion stage by stage
  • Detailed view of each SPOC's submission with diff from previous week
  • POD-level commentary and approval before sending to Cluster Head
  • Escalation alerts for overdue SPOC submissions (ET-012)
  • Submit POD summary upward to Cluster Head
cluster-head screen

Cluster Head Screen

/workflow/cluster-head
cluster_head
  • Final stage of the delivery chain — receives POD Owner summaries
  • KPI strip: POD count, all-submitted indicator, total project count
  • Expand each POD row to read the full rollup with nested chain detail
  • Approve, return with comment, or acknowledge each POD summary
  • Priorities & Achievements Acknowledge button for Priorities & Achievements digest acknowledgement (Sprint 12)
  • Weekly digest email (ET-014) sent automatically by scheduler
  • Full cycle is complete when all POD summaries are acknowledged
pmo screen

PMO Screen

/workflow/pmo
pmo
  • Cross-cluster observer view — read-only access to all POD summaries
  • Tabbed view: All Projects / By POD / By Status
  • KPI strip: total projects, on-track count, at-risk count
  • Drill down into any project to read submission history
  • Export capability for offline reporting (CSV)
  • No approval actions — PMO is observational, not in the approval chain

Review Cycles

cycle-history screen

Cycle History Screen

/cycles/history
All authenticated users
  • Paginated list of all review cycles (past + current + upcoming)
  • Columns: cycle name, ISO week, status, next scheduled run, completion %
  • Status badges: Active / Complete / Pending / Upcoming
  • Click any cycle row to navigate to cycle detail
  • Filter by status, date range, or search by cycle name
  • Admin users can see the full run log for each cycle
cycle-detail screen

Cycle Detail Screen

/cycles/:id
All authenticated users
  • Full detail for a single review cycle identified by ID
  • KPI cards: overall completion %, submission counts, pending counts
  • Chain progress stepper: Project Lead → Project Manager → Delivery SPOC → Sales SPOC → POD Owner → Cluster Head
  • Per-stage completion breakdown with links to individual submissions
  • Timeline of scheduler events that fired during the cycle
  • Export cycle data as CSV for offline analysis

Priorities & Achievements

pa screen

Priorities & Achievements Screen

/pa
All roles with reporting relationships (incl. Project Contributor)
  • Two-panel layout: submission form (left) + team submission status (right sidebar)
  • Submit priorities for the current ISO week and achievements from last week
  • Free-text areas for Highlights and Lowlights (optional)
  • Save Draft preserves unsaved changes; Submit locks the form
  • Current Week / Next Week tabs — pre-plan next week's priorities & achievements as a draft anytime; Submit to the manager is disabled until one day before the week begins
  • Team Status sidebar shows direct reports' submission state (green/amber/red)
  • My Contributors card (for Project Leads): lists Project Contributors reporting to this PL with a Review → link into the bilateral review screen
  • Project Contributors land here as a P&A-only home — Ups & Downs / Cycle History are hidden for them
  • Triggered via ET-007 kickoff email (both manual pa_kickoff_all and automated Monday cron)
  • Supports combined week submissions (e.g. "2026-W22 & 2026-W23") from pa_kickoff_all
project contributor submission screen

Project Contributor Submission

/pa
project_contributor
  • P&A-only role at the bottom of the bilateral chain — a Project Contributor reports to a Project Lead (e.g. Gopal Krishna Tripathi & Shivsagar Mishra → Kuntal Singha, Black Sun)
  • Uses the same Priorities & Achievements submission screen as everyone else; their submission is reviewed bilaterally by their Project Lead
  • After the PL approves, the entry flows up the normal hierarchy: Project Contributor → PL → PM → Delivery SPOC → POD Owner → Cluster Head
  • Excluded from reports, dashboards, Ups & Downs, and project membership — visible only within the P&A workflow
  • Assigned in Admin → Users; the PC→PL mapping is managed in Admin → Reporting Relationships
pa-review screen

Project Manager Bilateral Review Screen

/pa/bilateral-review
pl pm delivery_spoc / sales_spoc / pod_owner / cluster_head
  • Each reviewer reviews their direct report's Priorities & Achievements submission in a bilateral context — a Project Lead reviews their Project Contributors, a PM reviews their PLs, and so on up the chain
  • Side-by-side view: direct report's submission vs. the reviewer's own this-week priorities
  • Tabbed view per direct report — navigate between all direct reports
  • Approve, return with comment, or escalate each Priorities & Achievements entry
  • Project Manager adds bilateral review note that becomes part of the audit trail
  • Completed reviews trigger ET-013 acknowledgement to the Project Lead
pa-digest screen

Cluster Head Priorities & Achievements Digest Screen

/pa/digest
cluster_head
  • Aggregated Priorities & Achievements digest for the Cluster Head — all PODs in scope
  • KPI strip: total PODs, submission rate %, current week
  • Grouped by POD — click to expand full team Priorities & Achievements list
  • Highlights reel: top priorities and achievements across cluster
  • Priorities & Achievements Acknowledge button — marks the digest as reviewed (Sprint 12)
  • Weekly digest is emailed automatically via ET-014 scheduler job
pa-history screen

Historical Priorities & Achievements Screen

/pa/history
All authenticated users
  • Archive of all past Priorities & Achievements submissions by the current user
  • Tabs: My Submissions / Team Submissions (if manager role)
  • Filter chips: by week, by submission status, by type
  • Click any row to expand and read the full entry
  • Export selected entries as CSV or PDF
  • Managers see all direct reports' historical entries under Team tab

Reports

reports screen

Reports Screen

/reports
All authenticated users admin (extended)
  • Ups & Downs Trend: SVG bar chart showing weekly ups vs downs counts over time
  • Priorities & Achievements Completion Rate: SVG line chart — % of team submitting Priorities & Achievements per week
  • Return Rate by Stage: Horizontal bar chart — % of submissions returned at each chain stage
  • Approval SLA Metrics: Card showing average time-to-approve at each stage
  • ViewToggle component switches between table view and chart view for each dataset
  • On-demand CSV export for all chart data sets
  • Admin users additionally see User Activity report and Return Rate exports (FEAT-10B)
  • Scheduled report delivery via email (FEAT-10A) — admins configure cadence in Admin → Reports

Account

profile screen

Profile Screen

/profile
All authenticated users
  • User info tab: display name, email, avatar (initials-based), role summary
  • Security tab: change password form with current password verification
  • MCP Guide tab: inline API token management and MCP server setup instructions — the server exposes 64 tools / 3 resources / 3 pre-built prompts
  • Personal Access Tokens: generate tokens prefixed pgmcp_ for MCP client auth
  • Token list shows name, created date, last used, expiry — revoke individually
  • Notification preferences (email / in-app toggles per notification type)
status screen

Status Screen

/status
All authenticated users
  • Real-time health indicators for API server, database, and scheduler service
  • Service health table: each service with status badge and last-checked timestamp
  • Automation enabled/disabled indicator (from SchedulerSettings)
  • API version and build timestamp displayed
  • Useful for support diagnostics — shows current user's JWT claims summary

Admin Portal

All admin screens are under /admin/* and require the admin role. The admin portal is accessible via the Admin link in the sidebar (visible only to admin users).

admin-projects screen

Admin — Projects

/admin/projects
admin
  • Full CRUD for projects: create, edit, deactivate
  • Assign projects to PODs; set project status (active/inactive)
  • Search and filter projects by name, POD, or status
  • Edit modal: project name, POD assignment, role assignments (Project Lead, Project Manager, etc.)
  • Shows all assigned Project Managers and Project Leads in the edit modal
  • Deactivation hides the project from workflow screens without deleting data
admin-pods screen

Admin — PODs

/admin/pods
admin
  • Full CRUD for PODs (Profit Delivery Units)
  • Assign POD Owner and Cluster Head to each POD
  • Project count badge shows how many projects belong to each POD
  • Edit modal: POD name, owner assignment, cluster head assignment
  • Deactivate POD hides it from workflow without deleting history
admin-users screen

Admin — Users

/admin/users
admin
  • User directory with search by name or email
  • Invite new user: sends ET-006 invitation email with activation link
  • Edit user roles (multi-select from all role types)
  • Activate / deactivate user accounts
  • Role badges shown inline; click to expand role + project assignments
  • Reset password sends a new activation email to the user
admin-scheduler screen

Admin — Scheduler

/admin/scheduler
admin
  • Configuration tab: enable/disable all automation globally (disableAllAutomation), per-notification toggles, manual cycle creation with project selection
  • Activity & Run Log tab: Upcoming Runs table + Run History table with status badges, duration, items affected, and expandable detail JSON
  • Run History filters: by job type, status (success / failed / skipped), date range — Export as CSV
  • Every execution is persisted to the scheduler_runs database table (jobType, status, trigger, startedAt, finishedAt, durationMs, itemsAffected, detail JSON)
All 9 Registered Scheduler Jobs
Job Type Label Cron / Schedule Email Template Description
cycle_creation Cycle Creation Poll Every minute — Checks active SchedulerCycle rows and auto-creates a new review cycle when the next run time is reached. Hidden from Upcoming Runs (covered by cycle table).
send_monday_kickoff Monday Priorities & Achievements Kickoff Mon 02:30 UTC ET-007 Sends weekly Priorities & Achievements kickoff email to all active Project Leads in projects with open cycles. Uses projectName, weekLabel, submissionLink tokens.
send_pl_submission_reminder Project Lead Submission Reminder Mon 11:00 UTC ET-008 Reminds Project Leads who haven't submitted by 11:00 Monday. Skipped if already submitted (idempotency guard via reminderSentLog).
send_cluster_head_digest Cluster Head Weekly Digest Fri 16:00 UTC ET-014 Sends aggregated weekly Priorities & Achievements digest to all Cluster Heads. Summarises all POD rollups received that week.
send_missed_submission_escalation Missed Submission Escalation Fri 14:00 UTC ET-012 Escalates to the manager when a team member has not submitted by Friday afternoon. Fires per active reporting relationship with missing submission.
send_invitation_reminders Invitation Reminders Daily 08:00 UTC ET-006 Re-sends account activation reminders to users who were invited but have not yet activated their account. Stops after 3 attempts.
run_reminder_engine General Reminder Engine Hourly ET-008/011/012 Orchestrates all time-sensitive reminders. Evaluates submission deadlines and fires the appropriate notification template for each overdue entity. Uses reminderSentLog to prevent duplicates.
run_scheduled_reports Scheduled Report Delivery Daily 06:00 UTC — Delivers reports configured in Admin → Reports. Checks each ScheduledReport row for due deliveries, generates the report data, attaches CSV, and emails to recipients.
pa_kickoff_all Priorities & Achievements Kickoff — All Direct Reports Manual only (▶ Run Now) ET-007 Sends ET-007 to every active direct report in the reportingRelationship table — covers ALL roles (Project Lead, Project Manager, Delivery SPOC, Sales SPOC, POD Owner, Cluster Head). weekLabel = previous week + current week combined (e.g. "2026-W22 & 2026-W23"). One email per unique recipient. Cron is set to Jan 1 (never auto-fires). API: POST /api/v1/admin/scheduler/jobs/pa_kickoff_all/fire
admin-email screen

Admin — Email Templates

/admin/email-templates
admin
  • View and edit all ET-001 to ET-022 email notification templates
  • Edit subject line and HTML body with live token preview
  • Supported tokens: {{userName}}, {{projectName}}, {{weekLabel}}, {{deadline}}, {{managerName}}, {{submissionLink}} and more
  • Test-send any template to a specified email address
  • Change history per template (audit trail)
  • Reset to default option available for each template
admin-rr screen

Admin — Reporting Relationships

/admin/reporting-relationships
admin
  • Manage the bilateral Priorities & Achievements reporting chain — who reports to whom
  • Supports all role combinations: Project Contributor → Project Lead, Project Lead → Project Manager, Project Manager → Delivery SPOC, Delivery SPOC → Sales SPOC, etc.
  • Add new relationship: select Direct Report + Manager from user search
  • Toggle active/inactive without deleting (preserves history)
  • This table is queried by the pa_kickoff_all scheduler job to send ET-007 to all direct reports across all roles
  • Also drives the Team Submission Status sidebar in PAScreen
admin-reports screen

Admin — Reports

/admin/reports
admin
  • Scheduled Reports tab: configure automated report delivery (FEAT-10A)
  • Create scheduled report: choose report type, recipients, cadence (weekly/monthly), day & time
  • Each scheduled report shows next delivery time and status (active/paused)
  • Export tab: on-demand CSV exports for User Activity and Return Rate data (FEAT-10B)
  • User Activity export: logins, submission counts, last active — filterable by date range
  • Return Rate export: submissions returned at each stage, by week/POD
admin-mcp-tokens screen

Admin — MCP Tokens

/admin/mcp-tokens
admin
  • Admin view of all Personal Access Tokens (PATs) issued across all users
  • PAT prefix: pgmcp_ — used for MCP server authentication
  • Columns: user, token name, created date, last used, expiry
  • Admin can revoke any token (e.g. for offboarding or security incidents)
  • Search by user or token name
  • Users manage their own tokens in Profile → MCP Guide tab
admin-mcp-log screen

Admin — MCP Interaction Log

/admin/mcp-log
admin
  • Audit log of all MCP tool calls made via the MCP server (FEAT-09C)
  • Columns: timestamp, user (token owner), tool called, request summary, status
  • Filter by user or tool name; paginated results
  • Failed calls shown with error detail on expand
  • Useful for auditing AI-assisted access to POD Governance data via Claude/MCP clients
  • Export as CSV for compliance reporting
admin-audit screen

Admin — Audit Log

/admin/audit-log
admin
  • Immutable log of all write operations across the system
  • Columns: timestamp, actor (user), action (CREATE/UPDATE/DELETE), entity type, entity ID
  • Filter by actor, action type, entity type, or date range
  • Expand any row to see before/after JSON diff for update events
  • Export filtered results as CSV for compliance and OWASP audit requirements
  • Sanitised log output — PII is masked in exported fields (OWASP QA fix)

POD Governance Implementation Documentation · v175 · Generated 2026-06-16 · Mockup reference (PAGES.md)