Oliver/npi-2026

DJP b171dc9f21 Add comprehensive README documentation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-04-02 14:53:24 -04:00

18 KiB

Raw Permalink Blame History

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.

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.

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:

Checklist Items — Evidence for gate exit criteria (e.g. test reports, sign-off documents)
Gate Approvals — Supporting documents uploaded during gate approval
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.

18 KiB Raw Permalink Blame History Unescape Escape

NPI Tracker

Table of Contents

Features

Tech Stack

Architecture

Getting Started

Prerequisites

Quick Start

Default Login

Ports

Environment Variables

Database Schema

Reference Tables (seeded on first run)

Project Instance Tables

Supporting Tables

Enums

API Reference

Authentication

Projects

Gates

Status Updates

RACI

PPPP

Triggers

Attachments

Notifications

Reference Data

Health

Frontend Pages

NPI Process Overview

Product Categories

RACI Matrix

Triggers

File Attachments

Email Notifications

Development

Hot Reload Development Mode

Rebuilding After Code Changes

Database Access

Regenerating Seed Data

Project Structure

License

18 KiB

Raw Permalink Blame History