NPI Tracker

A full-stack New Product Introduction (NPI) gate tracking tool that manages products through a 13-gate governance process (G0–G12). Built for teams that need structured oversight of product development — from intake and classification through to end-of-life.

---

Table of Contents

• Features
• Tech Stack
• Architecture
• Getting Started
• Environment Variables
• Database Schema
• API Reference
• Frontend Pages
• NPI Process Overview
• Product Categories
• RACI Matrix
• Triggers
• File Attachments
• Email Notifications
• Development
• Project Structure

---

Features

• 13-Gate Process (G0–G12) — Structured governance from intake to end-of-life with exit criteria checklists per gate
• 4 Product Categories — Category I, IB, II, III with automatic gate tailoring based on classification
• RACI Matrix — Role-based responsibility tracking (Responsible, Accountable, Consulted, Informed) auto-populated from templates
• Trigger-Based Tailoring — Conditional gates activated by product characteristics (sensitive data, connectors, client-facing, etc.)
• Kanban Board — Visual drag-and-drop board showing products grouped by current gate
• Gantt / Timeline View — Multi-project timeline with target vs actual date tracking using D3.js
• File Attachments — Upload images, PDFs, and Office documents as evidence on gates, checklist items, and status updates with in-browser preview
• PPPP Framework — Positioning, Pricing, Packaging, and Proposition tracking for Category III commercial products
• Status Updates — Progress notes, blockers, decisions, and general notes with author tracking
• Dashboard — Executive overview with status counts, gate distribution, overdue items, and recent activity
• Email Notifications — Overdue reminders and gate reviews via Mailgun (stubbed for development)
• Audit Log — All changes tracked with actor, action, entity, and timestamp
• Simple Auth — Shared password gate for team access (no individual accounts)

---

Tech Stack

Layer	Technology
Frontend	React 18, Vite 6, Mantine UI 7, React Router 6, TanStack React Query 5, D3.js 7, Hello Pangea DnD
Backend	Node.js, Express 4, TypeScript 5
Database	PostgreSQL 16
File Uploads	Multer
Scheduling	node-cron
Containerisation	Docker Compose
Reverse Proxy	Nginx (production frontend)
Font	Montserrat
Colour Palette	#FFC407 (amber), #000000 (black), #FFFFFF (white)

---

Architecture

┌─────────────┐     ┌─────────────┐     ┌─────────────────┐
│  React App  │────▸│  Express    │────▸│  PostgreSQL 16   │
│  (Nginx)    │     │  API        │     │                  │
│  Port 4011  │     │  Port 4010  │     │  Port 5434       │
└─────────────┘     └──────┬──────┘     └─────────────────┘
                           │
                    ┌──────┴──────┐
                    │  Scheduler  │  (node-cron background jobs)
                    └─────────────┘

All services are orchestrated via Docker Compose with persistent volumes for database data and file uploads.

---

Getting Started

Prerequisites

• Docker & Docker Compose

Quick Start

# 1. Clone the repository
git clone git@bitbucket.org:zlalani/npi-2026.git
cd npi-2026

# 2. Create environment file
cp .env.example .env
# Edit .env and set your passwords

# 3. Start all services
docker compose up -d

# 4. Access the app
open http://localhost:4011

The database is automatically initialised with the full NPI gate structure, steps, and RACI templates on first run.

Default Login

Password: npi2026 (set via APP_PASSWORD in .env)

Ports

Service	Port
Frontend (Web)	4011
API	4010
PostgreSQL	5434

---

Environment Variables

Create a .env file from .env.example:

# Database
POSTGRES_DB=npi_tracker
POSTGRES_USER=npi
DB_PASSWORD=changeme_in_production

# Application
APP_PASSWORD=npi2026
NODE_ENV=development
API_PORT=3001

# Mailgun (optional — logs to console when not configured)
MAILGUN_API_KEY=
MAILGUN_DOMAIN=
MAILGUN_FROM=npi-tracker@yourdomain.com

# JWT Secret
JWT_SECRET=changeme_jwt_secret

---

Database Schema

Reference Tables (seeded on first run)

Table	Purpose
gates	13 NPI gate templates (G0–G12) with names and descriptions
gate_applicability	Which gates apply to which categories + trigger-based flags
gate_steps	Exit criteria steps within each gate, per category
gate_step_raci	Template RACI assignments per step per role

Project Instance Tables

Table	Purpose
projects	Products being tracked (name, category, owners, status)
project_gates	Gate instances per project (status, dates, approvals)
project_gate_checklist	Checklist items per gate (completion, evidence, notes)
project_raci_assignments	Actual people assigned to each role for a project
project_triggers	Trigger flags per project
status_updates	Progress notes and blockers
pppp_tracking	PPPP framework data (versioned)

Supporting Tables

Table	Purpose
attachments	File uploads with metadata
notifications	In-app and email notification records
audit_log	Change history for all entities

Enums

• category: I, IB, II, III
• project_status: active, on_hold, completed, cancelled
• gate_status: not_started, in_progress, blocked, passed, skipped, failed
• raci_type: R, A, C, I
• update_type: progress, blocker, decision, note

---

API Reference

Base URL: /api

Authentication

Method	Endpoint	Description
POST	/auth/login	Login with password
POST	/auth/logout	Logout and clear session
GET	/auth/check	Verify authentication status

Projects

Method	Endpoint	Description
GET	/projects	List projects (filter by category, status, gate)
GET	/projects/dashboard	Dashboard aggregations
GET	/projects/kanban	Kanban view (grouped by gate)
GET	/projects/:id	Get project with gates and triggers
GET	/projects/:id/timeline	Project timeline/Gantt data
POST	/projects	Create new project
PATCH	/projects/:id	Update project

Gates

Method	Endpoint	Description
GET	/gates/project/:projectId	All gates for a project
GET	/gates/:gateId	Gate detail with checklist and RACI
PATCH	/gates/:gateId	Update gate (status, dates)
PATCH	/gates/:gateId/checklist/:itemId	Toggle/update checklist item
POST	/gates/:gateId/approve	Approve gate and advance project

Status Updates

Method	Endpoint	Description
GET	/updates/project/:projectId	List status updates
POST	/updates/project/:projectId	Create status update

RACI

Method	Endpoint	Description
GET	/raci/project/:projectId	Get RACI assignments
GET	/raci/project/:projectId/matrix	Full RACI matrix (template)
PUT	/raci/project/:projectId	Bulk update RACI assignments

PPPP

Method	Endpoint	Description
GET	/pppp/project/:projectId	Get latest PPPP data
GET	/pppp/project/:projectId/history	PPPP version history
PUT	/pppp/project/:projectId	Create/update PPPP

Triggers

Method	Endpoint	Description
GET	/triggers/project/:projectId	Get triggers
PUT	/triggers/project/:projectId	Update triggers

Attachments

Method	Endpoint	Description
POST	/attachments/upload	Upload file (multipart, 20MB max)
GET	/attachments/:id/download	Download file
GET	/attachments/:id/preview	Preview file (inline)
GET	/attachments/entity/:type/:id	List attachments for entity
GET	/attachments/project/:projectId	List all project attachments
DELETE	/attachments/:id	Delete attachment

Notifications

Method	Endpoint	Description
GET	/notifications	List notifications
PATCH	/notifications/:id/read	Mark as read
POST	/notifications/chase	Send chase notifications

Reference Data

Method	Endpoint	Description
GET	/reference/gates	All gate templates
GET	/reference/gates/:num/steps	Steps for a gate
GET	/reference/roles	All RACI roles
GET	/reference/timeline	Multi-project timeline data

Health

Method	Endpoint	Description
GET	/health	Health check

---

Frontend Pages

Route	Page	Description
/login	Login	Password authentication
/	Dashboard	Executive overview — status counts, gate distribution, overdue items
/projects	Project List	All projects with category/status/gate filters
/projects/new	Product Registry	4-step wizard: Basic Info → Triggers → Ownership → Review
/projects/:id	Project Detail	Tabs: Overview, Gates, RACI, Updates, Files, PPPP
/projects/:id/gate/:gateId	Gate Detail	Checklist, progress bar, dates, file attachments, approval
/kanban	Kanban Board	Drag-and-drop board grouped by gate
/timeline	Timeline	D3.js Gantt chart with target vs actual bars

---

NPI Process Overview

The NPI process consists of 13 gates that products progress through sequentially:

Gate	Name	Purpose
G0	Intake, Classification & Tailoring	Initial product classification and gate tailoring
G1	Idea/Request Filtering	Ideation and initial feasibility
G2	Prioritisation	Business prioritisation and resource allocation
G3	Concept Development	Detailed concept development (trigger-based for Cat I)
G4	Design	Architecture and design review
G5	Build & Test	Iterative development and testing
G6	Launch Readiness	Pre-launch validation
G7	Feature Handover	Handover to operations/support
G8	Staging Testing	Staging environment validation
G9	UAT	User acceptance testing
G10	Live Deployment + Beta	Production deployment and beta period
G11	Support, Hypercare & BAU	Post-launch support and transition to BAU
G12	End of Life	Product retirement

Each gate has exit criteria (checklist items) that must be completed before the gate can be approved. Gate applicability varies by product category and triggers.

---

Product Categories

Category	Description	Gates
I	Internal lightweight products	Minimal gates, more with triggers
IB	Moderate governance products	Subset of full gates
II	Full internal governance	Most gates required
III	Full governance + commercial	All gates + PPPP framework

When a product is registered, the system automatically generates the applicable gates, checklist items, and RACI roles based on its category and triggers.

---

RACI Matrix

Each gate step has predefined RACI assignments across 20+ roles:

• R (Responsible) — Does the work
• A (Accountable) — Ultimately answerable
• C (Consulted) — Provides input
• I (Informed) — Kept in the loop

When a project is created, RACI roles are auto-populated from templates. Known roles (Requestor, Product Owner, Tech Lead, Sponsor, Commercial Owner) are pre-filled from the registration form. Assignments can be edited on the project's RACI tab.

---

Triggers

Triggers are product characteristics that affect which gates are required:

Trigger	Description
sensitive_data	Processes sensitive or personal information
connectors	Uses external integrations or connectors
write_actions	Performs write or delete operations
high_cost	May incur significant computational cost
client_facing	Visible to end users or clients
commercial	Has commercial or revenue implications

Triggers are set during product registration and can be updated later. They dynamically affect gate applicability — for example, Category I products gain additional gates when triggers are active.

---

File Attachments

Files can be attached at three levels:

1. Checklist Items — Evidence for gate exit criteria (e.g. test reports, sign-off documents)
2. Gate Approvals — Supporting documents uploaded during gate approval
3. Project Level — General reference files accessible from the project's Files tab

Supported formats: PNG, JPEG, GIF, WebP, PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, CSV, TXT

Max file size: 20MB

Preview: Images and PDFs can be previewed in-browser. Text and CSV files are rendered inline. Office documents are download-only.

Files are stored in a Docker volume (uploads) and persisted across container restarts.

---

Email Notifications

Email integration uses Mailgun (currently stubbed — logs to console in development).

Notification types:

• Overdue reminders — Automatic alerts for items past their target date
• Gate reviews — Manual chase for pending gate approvals
• Weekly digests — Scheduled summary of project progress

To enable emails, configure MAILGUN_API_KEY, MAILGUN_DOMAIN, and MAILGUN_FROM in .env.

---

Development

Hot Reload Development Mode

docker compose -f docker-compose.dev.yml up -d

This mounts source code directly into containers with hot reload enabled for both API and frontend.

Rebuilding After Code Changes

# Rebuild specific service
docker compose build api
docker compose build web

# Restart
docker compose up -d api web

Database Access

# Connect to PostgreSQL
docker compose exec db psql -U npi -d npi_tracker

# Apply new migration scripts
docker compose exec db psql -U npi -d npi_tracker -f /docker-entrypoint-initdb.d/006_attachments.sql

Regenerating Seed Data

If the NPI Excel file is updated, regenerate the seed SQL:

cd scripts
npm install
node parse-excel.mjs

This outputs 003_seed_steps.sql and 004_seed_raci.sql.

---

Project Structure

NPI_2026/
├── api/                          # Express API (TypeScript)
│   ├── src/
│   │   ├── config/               # Database + environment config
│   │   ├── middleware/            # Auth + error handling
│   │   ├── routes/               # All API route handlers
│   │   ├── utils/                # Gate tailoring logic
│   │   ├── index.ts              # API entry point
│   │   └── scheduler.ts          # Background cron jobs
│   ├── Dockerfile
│   └── package.json
│
├── web/                          # React frontend (Vite + Mantine)
│   ├── src/
│   │   ├── api/                  # Axios client + API hooks
│   │   ├── components/
│   │   │   ├── common/           # Logo, FileUpload, AttachmentList
│   │   │   └── layout/           # AppLayout (header + sidebar)
│   │   ├── pages/                # All page components
│   │   ├── types/                # TypeScript interfaces
│   │   ├── theme.ts              # Mantine theme (Montserrat, amber)
│   │   └── App.tsx               # Router config
│   ├── nginx.conf                # Production reverse proxy
│   ├── Dockerfile
│   └── package.json
│
├── db/
│   └── init/                     # SQL init scripts (run on first start)
│       ├── 001_schema.sql        # Tables, enums, indexes
│       ├── 002_seed_gates.sql    # 13 gate definitions
│       ├── 003_seed_steps.sql    # 196 gate steps (from Excel)
│       ├── 004_seed_raci.sql     # RACI templates (from Excel)
│       ├── 005_seed_evidence_ref.sql
│       └── 006_attachments.sql   # Attachments table
│
├── scripts/                      # Excel parser utilities
├── logo-preview/                 # Logo design options (SVG)
├── docker-compose.yml            # Production orchestration
├── docker-compose.dev.yml        # Development orchestration
└── .env.example                  # Environment variable template

---

License

Internal use only. Proprietary.