Welcome to the NPD Lifecycle Manager — an enterprise-grade tool designed specifically for food manufacturing companies to manage the full lifecycle of New Product Development (NPD). From initial concept through formulation, costing, approval workflows, and into production, this system provides a single source of truth for every new product your organisation develops.

For a high-level overview of the system’s purpose, benefits, and rules of operation, visit the About & Guide page.

The core workflow follows a structured path through project statuses:

• Draft — Initial creation and formulation entry
• In Review — Submitted for multi-stage approval
• Approved — All workflow stages signed off
• Production — Handed over to manufacturing

Use the sidebar navigation to access all areas of the system. Each section is described in detail below.

New to the system? These are the most common tasks and exactly where to do them. Detailed instructions for each appear in the numbered sections below.

Abbreviations used throughout the system, defined once here for reference.

• NPD — New Product Development; the end-to-end process of taking a product from concept to production.
• RAG — Red / Amber / Green status indicator. Green = healthy margin, Amber = marginal/attention needed, Red = below target or blocked.
• M1 (Margin 1) — The primary margin, used to derive the standard selling price from cost.
• M2 (Margin 2) — The secondary margin (e.g. distributor / customer margin), giving a second selling price and profit figure.
• CPA — Cost Per Analysis; non-formulation costs linked to a product (listing fees, lab testing, marketing, certification).
• KPI — Key Performance Indicator; the summary metrics shown on the Dashboard.
• Cost/kg, Selling/kg, M2/kg — The per-kilogram cost, selling price, and Margin 2 profit.
• Recipe mode — Products built from a formulation of ingredients (sausages, patties, mince).
• Primal mode — Cut-based products defined by cut specs and yield rather than a recipe (steaks, chops, fillets).
• Phase — The lifecycle stage: Development → Trial → Scale-Up → Production.

The Dashboard is your home page and provides an at-a-glance overview of all NPD activity across the organisation.

• Stat Cards — Show key metrics including total projects, projects in review, approved, on hold, rejected, cancelled, and in production. These update in real time as data changes.
• Import Demo Data — If the database is empty, you can click the "Import Demo Data" button to populate the system with sample users, ingredients, workflows, and projects. This is useful for evaluation and training purposes.
• Portfolio Analytics — Visual charts showing the distribution of projects by status (donut chart) and by lifecycle phase (bar chart), so you can see the shape of your pipeline at a glance.
• Cost Overview — The dashboard displays a summary of cost distribution across all active projects, helping management quickly identify high-cost items and budget allocation.
• Recent Projects — A quick-access list of the most recently created or updated projects, with status badges and key details. Rejected projects are automatically hidden from this view to keep the focus on active work. A banner shows the count of hidden rejected projects with a link to view them.

Projects are the core entity in the NPD Lifecycle Manager. Each project represents a single new product being developed.

Product Modes: Recipe vs Primal

When creating a project, you must first select the product mode:

• RECIPE — Batch-based formulation with ingredients and percentages. Use for sausages, patties, mince, marinades, plant-based products, and any product with a recipe.
• PRIMAL — Cut-based product specification. Use for steaks, chops, fillets, roasts, and whole primal cuts. Defines cut weight, thickness, pieces per batch, primal source, and yield percentage.

The product mode determines which fields and tabs are shown on the project detail page. Recipe products show the Formulation tab; Primal products show the Cut Specs tab with yield analysis.

Lifecycle Phases

Every project progresses through four lifecycle phases. At each phase, the full workflow approval cycle must be completed before advancing:

• Development — Initial creation and formulation/specification. First round of approvals.
• Trial — Small controlled batch production. Quality testing and evaluation. Batch size scales up automatically if pre-configured.
• Scale-Up — Larger production batch with full testing cycle. All approvals must pass again.
• Production — Final rollout. When all approvals pass at this phase, the project is marked as "In Production".

The phase progress bar on the project detail page shows the current position. Use the "Advance to [Phase]" button for manual phase advancement, or let the workflow engine advance automatically when all stages are approved.

Creating a New Project

Navigate to the Projects page and click "New Project". Select your product mode (Recipe or Primal), then fill in the fields:

• Project Name — A descriptive name for the product (e.g., "Premium Boerewors 500g").
• Product Type — The category. Options change based on mode (recipe: Sausage, Burger Patty, etc. | primal: Steak, Chop, Fillet, etc.).
• Department / Category — Business division and product range. Free-text with autocomplete.
• Recipe fields — Dev Batch Size (kg), Target Weight (g), plus optional Trial/Scale-Up/Production batch sizes for phase planning.
• Primal fields — Primal Source, Cut Weight (g), Cut Thickness (mm), Pieces per Batch, Yield %.
• Workflow Template — The approval workflow to assign. The project will progress through all stages at each lifecycle phase.

Project Statuses

• draft — The project is being set up. Formulation and costing can be edited freely.
• in_review — The project has been submitted for approval and is progressing through workflow stages.
• approved — All required workflow stages have been signed off. The product is cleared for production.
• rejected — The project was rejected during the approval process. It can be revised and resubmitted.
• on_hold — The project is temporarily paused and not progressing through any workflow.
• cancelled — The project has been permanently cancelled and will not proceed.
• production — The product has been handed over to manufacturing and is actively being produced.

Priority Levels

• low — Standard timeline, no urgency.
• medium — Normal priority, standard processing.
• high — Elevated priority, expedited review recommended.
• critical — Urgent, requires immediate attention from all approvers.

The Formulation tab on a project detail page allows you to build the product recipe by adding ingredients from the ingredients library.

• Adding Ingredients — Click "Add Ingredient" to open the modal. Select an ingredient, then enter either the quantity or the percentage — the other value is auto-calculated based on the batch size. A live cost preview shows the estimated line cost before you add it.
• Bidirectional Calculation — The quantity and percentage fields work in both directions. Enter a quantity (e.g., 10 kg) and the percentage is auto-calculated (e.g., 10% of a 100 kg batch). Or enter a percentage (e.g., 5%) and the quantity is derived (e.g., 5 kg for a 100 kg batch). The batch size is displayed in the modal for reference.
• Quantity — The amount of the ingredient required per batch, expressed in the ingredient's configured unit (kg, litres, units, etc.).
• Percentage — The proportion of this ingredient in the total batch. Auto-derived from quantity ÷ batch size. The formulation table colour-codes the total: green (≥95%), amber (<95%), red (>100%).
• Line Cost — Automatically calculated as quantity × ingredient cost per unit. This value updates whenever the ingredient price or quantity changes.
• Total Ingredient Cost — The sum of all line costs in the formulation. This total feeds directly into the project's overall cost calculation as the "Ingredients" cost component.
• Editing a Line — Each formulation line has an "Edit" button. Click it to open an inline modal where you can adjust the quantity and percentage. Saving triggers an automatic recalculation of the line cost and total formulation cost.
• Removing a Line — Click the "Remove" button on any formulation line to delete it. The total ingredient cost and overall project costs are recalculated automatically.

The Images tab on a project detail page allows you to upload and manage visual documentation for the product.

• Supported Formats — JPG, JPEG, PNG, GIF, WebP, and BMP images up to 10 MB each.
• Image Types — Categorise each upload as General, Product Photo, Packaging, Label Design, or Lab Result.
• Captions — Add optional captions to describe each image for easy identification.
• Preview — Images are previewed before upload and displayed as a gallery within the project.

The Quality tab allows you to submit and track quality evaluations throughout the product development process.

• Evaluation Types — Quality, Sensory, Lab, or Shelf Life evaluations.
• Sensory Scores — Rate Appearance, Texture, Flavour, Aroma, and Overall on a scale of 1–10 using interactive range sliders.
• Pass / Fail / Conditional — Record the evaluation outcome.
• Batch Tracking — Link evaluations to specific batch numbers for traceability.
• Activity Log — Each evaluation automatically creates an activity note on the project for full audit trail.

The costing system provides a comprehensive breakdown of all costs associated with producing a product. Each project has six cost components, plus deductions and adjustments, that combine to produce the total cost.

Cost Components

• Ingredients Cost — Automatically calculated from the formulation. This is the sum of all ingredient line costs (quantity × cost per unit).
• Labour Cost — Represents the direct labour cost for producing one batch.
• Overhead Cost — Covers factory overhead, utilities, equipment depreciation, and other indirect costs per batch.
• Packaging Cost — Covers all packaging materials per batch (films, labels, trays, cartons).
• Transport Cost — Distribution and logistics cost per batch. Supports all three cost input modes.
• By-Product Recovery — Non-waste by-products (e.g., fat trim sold for rendering) are automatically deducted from the total cost. See the By-Products section for details.

Cost Input Modes

Each cost component (labour, overhead, packaging, transport, rebate, promo) supports three input modes. Select the mode from the dropdown next to each cost field:

• Full Value — Enter the total cost for the entire batch. Used as-is in the calculation.
• Per kg — Enter the cost per kilogram. The system multiplies by the batch size to get the full batch value.
• Per Unit — Enter the cost per finished unit. The system multiplies by (batch size × 1000 ÷ target weight) to get the full batch value.

Manufacturing Loss

The manufacturing loss percentage accounts for product lost during production (e.g., evaporation, trimming waste, spillage). When set, the system applies a loss multiplier of 1 ÷ (1 - loss% ÷ 100) to the total cost. For example, a 5% manufacturing loss multiplies the total cost by 1.0526, reflecting that you need to produce more raw product to achieve the target output.

Deductions: Rebate & Promo Value

• Rebate Value — A supplier or volume rebate that reduces the total cost. Supports all three cost input modes (full value, per kg, per unit). Deducted from the gross cost before margin calculation.
• Promo Value — A promotional discount or allowance that reduces the total cost. Also supports all three cost input modes. Deducted alongside the rebate.

Calculated Values

• Gross Cost — (Ingredients + Labour + Overhead + Packaging + Transport) × Loss Multiplier
• Total Cost — Gross Cost − Rebate − Promo − By-Product Recovery (minimum R0.00)
• Cost per kg — Total Cost ÷ Batch Size (kg). Useful for comparing products of different batch sizes.
• Cost per Unit — Cost per kg × (Target Weight ÷ 1000). The cost of producing a single finished unit.

Margin & Selling Price

• Primary Margin — The desired profit margin as a percentage of the selling price.
• Selling Price — Calculated as Total Cost ÷ (1 - Margin%). For example, a total cost of R100 with a 35% margin gives a selling price of R153.85.
• Secondary Margin — An optional additional margin applied on top of the primary selling price. Useful for multi-tier pricing (e.g., distributor margin on top of manufacturer margin). Calculated as Selling Price ÷ (1 - Secondary Margin%).

Cost Analysis Page

The dedicated Cost Analysis page (accessible from the sidebar) provides a comparative view of costs across all projects. It displays cost breakdowns, cost-per-kg rankings, and margin analysis to help management make informed pricing decisions.

The workflow system provides structured, multi-stage approval processes for new products. Workflows ensure that every product passes through the required sign-offs before it can move to production.

Workflow Templates

Workflow templates define the stages a project must pass through. Each template contains one or more stages in a defined order. A default workflow template can be set and will be automatically assigned to new projects.

Workflow Stages

• Stage Name — A descriptive name (e.g., "R&D Review", "QA Sign-off", "Finance Approval").
• Order — The sequence position of this stage in the workflow. Stages are processed in ascending order.
• Required Role — The minimum user role required to approve this stage (e.g., manager, user).
• Required Approvers — The number of approvals needed to pass this stage.
• Auto Advance — When enabled, the project automatically moves to the next stage once the required number of approvals is met.

Approval Process

• Approve — The approver signs off on the current stage. Once the required number of approvals is met, the project advances to the next stage (or is marked "approved" if it was the final stage).
• Reject — The approver rejects the project. The project status changes to "rejected" and the workflow is halted. The project can be revised and resubmitted.
• Request Changes — The approver requests modifications before they can approve. The project creator is notified and can make changes before resubmitting.

Workflow Enforcement

The system strictly enforces the workflow process. A project cannot be manually set to “approved” status while it has an active workflow with remaining stages. The “approved” option is removed from the status dropdown until all workflow stages are completed. This ensures every product passes through the required sign-offs — R&D Review, QA Sign-off, Finance Approval, and Operations Sign-off — before it can move to production.

The Ingredients Library is your central catalog of all raw materials, additives, packaging materials, and other components used in product formulations.

Bulk Import from CSV

To add many ingredients at once, click Import CSV on the Ingredients page. Use the Download a CSV template link to get a correctly-formatted starter file. Required columns are name, category, unit, and cost_per_unit; optional columns are supplier, code, and allergens. Leave code blank to have it auto-generated. After importing, a summary shows how many ingredients were created and lists any rows that were skipped (duplicate codes, missing fields, or invalid costs) with the reason — the rest still import successfully.

Core Fields

• Ingredient Code — A unique identifier for the ingredient (e.g., "MEAT-001", "SPICE-002"). If left blank, the system auto-generates a code based on the category prefix and a random 4-digit suffix (e.g., selecting category "Spice" auto-generates a code like "SPICE-3847").
• Name — The descriptive name of the ingredient.
• Category — The classification. Available categories: Meat, Spice, Casing, Additive, Packaging, Preservative, Flavouring, Filler, Plant Protein, Plant Fat, Plant Additive, Water, and Other.
• Unit — The unit of measure (kg, litres, units, metres, each).
• Cost per Unit — The current cost for one unit of this ingredient. Changes here automatically recalculate all project formulation costs.
• Supplier — The primary supplier for this ingredient.

Allergens

Each ingredient can be linked to one or more allergens using the multi-select checkboxes on the ingredient form. Allergens are managed centrally via the Allergens page (see Section 15). Common allergens include Gluten, Dairy, Soy, Eggs, Mustard, Celery, Sulphites, Lupin, Sesame, Fish, Crustaceans, Molluscs, Peanuts, and Tree Nuts.

When an ingredient with linked allergens is used in a project formulation, the project detail page automatically displays allergen warnings showing all allergens present across the formulation.

Operational Constraints

Each ingredient can also be linked to one or more operational constraints using multi-select checkboxes. Constraints represent production requirements or restrictions, such as "Cold Chain Required", "Halal Certified", "Kosher Certified", "Organic Only Line", or "Allergen-Free Zone". Constraints are managed centrally via the Constraints page (see Section 15).

Projects automatically aggregate constraint warnings from their formulation ingredients, displayed as constraint badges on the project detail page.

Auto-Generated Codes

When creating a new ingredient, the code field is optional. If left blank, the system automatically generates a code using the category prefix and a random 4-digit suffix (e.g., SPICE-3847, MEAT-1294). Category prefixes include MEAT, SPICE, CAS, ADD, PKG, PRES, FLAV, FILL, PB, FAT, PADD, WAT, and OTHER. You can also enter a custom code if preferred.

Important: When you update an ingredient's cost per unit, all projects that use that ingredient will have their formulation line costs and total project costs automatically recalculated.

The Users page allows administrators to manage system users, assign roles, and control access.

User Roles

• Admin — Full access to all features, including user management, settings, and system configuration.
• Manager — Can approve workflow stages, manage projects, and view reports. Cannot manage users or system settings.
• User — Standard access for creating and managing projects, adding formulations, and participating in workflows.
• Viewer — Read-only access. Can view projects, reports, and data but cannot create or modify anything.

Other User Fields

• Department — The organisational department the user belongs to (e.g., R&D, Operations, Quality Assurance, Finance, IT).
• Active Status — Users can be set to active or inactive. Inactive users cannot log in or participate in workflows but their historical data is preserved.

First-Launch Admin

On first launch, if no users exist in the database, the system automatically creates a default Admin account (email: admin@company.local, password: changeme). Sign in with these credentials and change the password immediately. The administrator can then create additional user accounts with passwords and reset passwords from the Users page.

Authentication

All users sign in with their email address and password. The system uses JWT (JSON Web Token) authentication — after signing in, a token is issued and sent with every API request. Tokens expire after 24 hours, requiring a fresh login. Passwords are hashed with bcrypt and never stored in plain text.

• Admin creates users — administrators create user accounts with a password via the Users page.
• Admin resets passwords — administrators can reset any user’s password from the Users page.
• Users change own password — any user can change their own password via the API (POST /api/auth/change-password).

Departments represent the organisational divisions within your company that participate in the NPD process. They are managed from the dedicated Departments page in the sidebar, which provides full CRUD management with search and active/inactive filtering.

Department Management

• Name — A unique department name (e.g., "R&D", "Quality Assurance", "Production", "Marketing").
• Description — An optional description of the department's role and responsibilities.
• Active Status — Departments can be activated or deactivated. Inactive departments are excluded from dropdowns but historical data is preserved.

Workflow Linking

Each department can be linked to a default workflow template. When a project is created and assigned to a department, the department's linked workflow is automatically assigned to the project. This ensures consistent approval processes within each division without manual workflow selection.

The Trials tab on a project detail page allows you to record and track trial production batches. Trial results become available once a project reaches the Trial phase or beyond.

Recording a Trial

• Batch Number — A unique identifier for the trial batch (e.g., "TRIAL-001", "T-2024-03-15").
• Trial Date — The date the trial was conducted.
• Input Weight (kg) — The total weight of raw materials used in the trial.
• Output Weight (kg) — The total weight of finished product produced.
• Pass / Fail — The outcome of the trial: Pass, Fail, or Conditional. Displayed as colour-coded badges in the trials table (green for pass, red for fail, amber for conditional).
• Recorded By — Automatically populated with the currently logged-in user's name. This provides accountability and traceability for each trial record.
• Notes — Free-text observations, issues, or adjustments made during the trial.

Auto-Calculated Fields

• Yield Percentage — Automatically calculated as (Output Weight ÷ Input Weight) × 100. Helps track production efficiency across trials.
• Waste (kg) — Automatically calculated as Input Weight − Output Weight. Tracks material loss during the trial.

Trial Additional Costs

Each trial batch can have unlimited additional cost entries recorded against it. This allows you to capture the true lifecycle cost of each trial run beyond the formulation model.

• Adding a Cost — Click “+ Add Cost” on the trial card. Select a cost type, enter the amount and description. Cost types include: Materials, Labour, Testing/Lab, Equipment, Transport, Packaging, Overhead, and Other.
• Total Trial Cost — Displayed on each trial card, summing all additional cost entries for that batch.
• Actual Cost per kg — Calculated as Total Trial Cost ÷ Output kg. Allows direct comparison of actual cost against the formulation model cost per kg.
• Removing a Cost — Click the × button on any cost chip to remove it from the trial.

The By-Products tab on a project detail page allows you to track secondary products and waste generated during production. This is particularly important for primal cut operations where significant by-products (fat trim, bone, offal) have recoverable value.

Adding a By-Product

• Name — Descriptive name (e.g., "Fat Trim", "Bone & Sinew", "Offal").
• Weight (kg) — The expected weight of this by-product per batch.
• Pieces — An optional piece count for the by-product (e.g., number of bone pieces, offal units). Useful for tracking discrete items alongside weight.
• Cost Value & Mode — The recovery value or disposal cost. Supports all three cost input modes: Full Value (total batch cost), Per kg (multiplied by weight), or Per Unit (multiplied by pieces). The default mode is Full Value.
• Is Waste — Toggle to mark this by-product as waste. Waste items are tracked for weight/yield analysis but are not deducted from the total cost. Only non-waste by-products (those with recoverable value) reduce the project cost.

Cost Integration

Non-waste by-products are automatically factored into the project cost calculation. Their resolved cost values (based on the selected cost mode) are deducted from the gross cost, reducing the total cost. For example, if a primal cut project generates R37.50 worth of fat trim, this amount is subtracted from the total production cost.

Editing a By-Product

Each by-product row in the table has an “Edit” button. Click it to open an inline modal where you can modify the name, waste status, weight, pieces, cost value, and cost mode. Saving changes automatically triggers a full cost recalculation for the project.

Adding, updating, or removing a by-product automatically triggers a full cost recalculation for the project.

The Versions tab on a project detail page allows you to create point-in-time snapshots of a project's costing and formulation. This provides a full audit trail of how costs evolve over the product lifecycle.

Creating a Version

• Version Name — A descriptive label (e.g., "Initial costing", "Post-trial adjustment", "Final production costing").
• Auto-Numbered — Version numbers are automatically assigned in sequence (v1, v2, v3, etc.).

Captured Data

Each version snapshot captures:

• Total Ingredient Cost — The formulation cost at the time of the snapshot.
• Total Cost — The fully calculated project cost including all components, deductions, and loss.
• Selling Price — The margin-adjusted selling price at the time.
• Batch Size (kg) — The batch size when the version was created.
• Phase — The lifecycle phase (Development, Trial, Scale-Up, Production) when the snapshot was taken.
• Formulation Snapshot — A complete JSON capture of the formulation at that point in time, preserving the exact ingredient quantities and percentages for historical reference.

Version Comparison

The versions table displays all snapshots in chronological order, allowing you to compare how costs have changed across phases and iterations. This is invaluable for tracking cost drift and justifying pricing decisions to management.

The system provides centrally managed lists of allergens and operational constraints that can be linked to ingredients.

Allergen Management

• Allergen List — Managed from the dedicated Allergens page in the sidebar. The page provides full CRUD management: add new allergens with a name, code, and description; edit existing allergens; activate or deactivate them. Search and filter controls help manage large allergen lists. The demo data includes the 14 major food allergens (Gluten, Dairy, Eggs, Soy, Peanuts, Tree Nuts, Fish, Crustaceans, Molluscs, Celery, Mustard, Sesame, Sulphites, Lupin).
• Ingredient Linking — When creating or editing an ingredient, select applicable allergens from the checkbox list. These are stored as many-to-many relationships.
• Project Warnings — The project detail page automatically scans all formulation ingredients and displays red allergen warning badges for any allergens present. This supports food safety compliance and accurate product labelling.

Constraint Management

• Constraint List — Managed from the dedicated Constraints page in the sidebar. The page provides full CRUD management: add new constraints with a name, type (Flavourant, Allergen Cross, Cleaning Required), severity (Warning, Critical), and description; edit existing constraints; activate or deactivate them. Filters for search, type, severity, and active status are provided.
• Ingredient Linking — Assign constraints to ingredients the same way as allergens, using multi-select checkboxes.
• Project Warnings — Constraint badges appear in amber/warning style on the project detail page, alerting production teams to any special requirements for the product run.

The Reports page provides analytical views of your NPD portfolio, helping management make data-driven decisions.

• Dashboard Statistics — High-level KPIs including total project count and projects by status (in review, approved, on hold, rejected, cancelled, in production).
• RAG Status Panel — The main dashboard includes a Red/Amber/Green health panel showing all active projects colour-coded by health status. Click any colour button to filter the list. See Section 20 for full details.
• Cost Breakdown Reports — Detailed analysis of how costs are distributed across ingredients, labour, overhead, and packaging for each project.
• Status Distribution — Visual breakdown of how many projects are in each status, helping identify bottlenecks in the approval pipeline.
• Product Type Filtering — Filter reports by product type to analyse specific categories (e.g., all sausage products, all burger patties).

The Settings page provides comprehensive system configuration, managed entirely through the in-app UI. All settings are persisted to a configuration file with sensitive values (passwords, secret keys) encrypted using Fernet encryption.

General Settings

• Application Name — Customise the display name shown in the header and browser title.
• Company Name & Logo — Brand the system with your organisation’s name and logo. The Company Name and Logo URL (a web URL or a /static/… path) appear on the login page and on every Product Specification Sheet. A live preview of the logo is shown as you type.
• Currency — Set the currency symbol (e.g., R) and code (e.g., ZAR) used across all cost displays and reports.

Database Configuration

• SQLite (Default) — Zero-configuration file-based database. Ideal for single-user or small team deployments.
• Microsoft SQL Server — Enterprise database support via pyodbc. Configure host, port, database name, credentials, and driver. Use the "Test Connection" button to verify connectivity before saving.
• Active database banner — The Database Configuration card shows the connection the app is actually using right now and where it came from, so a misconfigured deployment is easy to spot.
• Environment-managed (read-only) — When a DATABASE_URL (or standard PG*) environment variable is set, it takes priority over everything here. In that case the form reflects the live backend and is locked read-only, because saving these fields would have no effect. To change the database, update the environment variable and restart.
• Important — Changing database settings requires an application restart to take effect.

Email (SMTP) Settings

• SMTP Configuration — Configure host, port, username, password, sender address, and TLS settings for outbound email notifications.
• Email Notification Log — A chronological log of all email notifications queued by the system. Shows recipient, subject, status, and timestamp. Email dispatch requires a configured SMTP server; without one, notifications are still recorded in the log but not delivered.
• When emails are sent — Four events trigger mail: a welcome email to a newly-created user with their sign-in details; a password-reset notice when an admin resets a user's password; an account activated/deactivated notice when a user's access status changes; and a project status-change notification to all admins, managers, and the project creator. Each user-account email can be toggled off at the point of action (Add User / Reset Password / Edit User). All messages use one branded, company-styled HTML layout (with a plain-text fallback) so they match the rest of the system.

Security

• Secret Key — Application secret key used for security operations. Auto-generated on first run. Sensitive values are displayed as masked placeholders (••••••••) in the UI.
• Encryption at Rest — Sensitive configuration values (passwords, secret keys) are encrypted using Fernet symmetric encryption before being stored in the configuration file.
• Security Headers — The application sets security headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Permissions-Policy) on all responses.
• CORS Protection — Cross-Origin Resource Sharing is restricted to the configured application URL to prevent unauthorised cross-origin API access.
• File Upload Safety — File uploads are validated by extension (images only), limited to 10 MB, and stored with randomised filenames to prevent path traversal.
• Input Validation — All API inputs are validated via Pydantic schemas with strict type checking, field length limits, and pattern constraints.

The system includes a comprehensive demo dataset for evaluation, training, and testing purposes. It is designed to exercise every feature of the system so you can explore a realistic, fully-populated workspace before entering your own data. Load and remove it at any time from the Demo page or from Settings → Demo Data. For a project-by-project breakdown of the dataset, see the Demo page.

What Gets Imported

• Users — 5 demo users across Admin, Manager, and User roles (all with password demo123, using @excellentmeat.co.za addresses).
• Ingredients — 39 ingredients across all categories (meats, spices, casings, additives, plant-based, packaging) with allergen and constraint linkages.
• Workflow Template — 1 template with 4 stages (R&D Review, QA Sign-off, Finance Approval, Operations Sign-off).
• Projects — 13 sample projects covering steaks (primal), sausages, burger patties, and plant-based products across every status and lifecycle phase.
• Departments — 5 departments (Retail, Food Service, Export, R&D, Operations), some linked to the approval workflow.
• Allergens — The 14 major food allergens (Gluten, Milk, Eggs, Soy, Mustard, Celery, Sesame, Sulphites, Lupin, Nuts, Peanuts, Fish, Crustaceans, Molluscs).
• Operational Constraints — 4 production constraints (Strong Flavourant, Allergen Cross-Contact, Spice Residue, Plant-Based Separation) linked to relevant ingredients.
• Trial Results — Batch trials with yield/waste and per-batch additional costs for projects in Trial phase and beyond.
• By-Products — Fat trim, bone/sinew and casing offcuts with cost-recovery values.
• Costing Versions & Snapshots — Scenario costing versions and point-in-time project snapshots capturing phase transitions.
• Quality Evaluations — Sensory, lab, and shelf-life evaluations with scores.
• Images — Product, packaging, label, and lab-result demo photos so the Images gallery is populated.
• Approvals, Notes, CPAs, Cooking Instructions & Email Log — Approval decisions (including a rejection), activity-log comments, non-formulation CPA costs, food-safety cooking steps, and notification history.

Selective & Incremental Import

You do not have to load everything. From Settings → Demo Data you can tick exactly which components to import, grouped into Master Data (allergens, constraints, departments, users, workflow, ingredients), Products (steaks / primal "breaks", sausages, patties, and the plant-based range — the recipe "assemblies"), and Project Enrichments (trials, by-products, costing versions, evaluations, approvals, notes, cooking instructions, CPAs, snapshots, email log, and images). Use Import selected for a chosen subset, or Import full dataset to load everything.

• Automatic dependencies — Choosing a product category also loads the master data its projects need (ingredients, users, workflow, departments), so a subset is always internally consistent.
• Incremental & idempotent — Importing only adds records that are missing. You can build the dataset up in stages, and re-running never duplicates data or errors on what is already loaded. A tick beside each component shows how many demo records of that type are already present.
• Enrichments follow projects — Enrichment components attach to whichever demo projects are present, so loading, say, just the steaks plus trials and images gives a focused but complete slice.

Data Safety

• Demo Flagging — All demo records are tagged with an internal is_demo flag. This ensures they can be cleanly separated from live production data.
• Purge Demo Data — Remove all demo-flagged records in one action, or use Remove selected to drop just the components you tick. Removal mirrors importing: dependent records cascade automatically (for example, removing ingredients also removes the demo products that use them; removing users or workflows also removes the approval decisions that reference them), so the result is always foreign-key-safe. Live data is left completely untouched.
• Clear All Data — A separate endpoint to remove ALL data (demo and live) from the system. Use with extreme caution — this is irreversible.
• Safe Coexistence — Demo data can coexist with live data. Import demo data to explore the system while real projects are in progress, then purge when no longer needed.

The NPD Lifecycle Manager exposes a full REST API for integration with external systems.

• Swagger UI — Interactive API documentation available at /docs. Test endpoints directly from the browser.
• ReDoc — Alternative API reference at /redoc with a clean, readable layout.

Key Endpoints

• Projects — /api/projects — Full CRUD, phase advancement, cost recalculation, formulation management, by-products, trials, versions, warnings.
• Ingredients — /api/ingredients — Full CRUD with allergen and constraint linking, auto-code generation.
• Users — /api/users — User management, role assignment, active status.
• Workflows — /api/workflows — Template and stage management, approval actions.
• Departments — /api/departments — Department CRUD with workflow linking.
• Allergens — /api/allergens — Allergen list management.
• Constraints — /api/constraints — Operational constraint management.
• Reports — /api/reports — Dashboard statistics and analytics.
• Settings — /api/settings — System configuration, database, email, and security settings.
• Demo Data — /api/seed-demo, /api/admin/purge-demo, /api/admin/clear-all — Import, purge demo data, or clear all data.
• Trial Costs — /api/projects/{id}/trials/{trial_id}/costs — Add and list additional costs per trial batch.
• CPA — /api/projects/{id}/cpas — Manage Cost Per Analysis entries with validity dates.
• Cooking Instructions — /api/projects/{id}/cooking-instructions — Manage food safety cooking steps.
• RAG Status — /api/reports/rag-status — Get Red/Amber/Green health status for all projects.

The RAG (Red / Amber / Green) Status Panel on the main dashboard provides an at-a-glance health overview of your entire NPD portfolio. Each project is automatically assigned a colour based on objective criteria.

Colour Definitions

• Green — Healthy / On Track: Projects that are approved, in production, actively in review (<7 days), or drafts less than 30 days old.
• Amber — Needs Attention: Projects on hold (normal priority), in review with no activity for 7+ days, or drafts not progressed for 30+ days.
• Red — Immediate Action Required: Rejected or cancelled projects, high/critical priority projects on hold, or critical priority projects stalled in review for 14+ days.

Using the Panel

• Filter Buttons — Click the Green, Amber, or Red buttons to filter the project list below to show only projects of that status. Click “All” to reset. The selected button is outlined.
• Reason Column — Each row shows the specific reason for its RAG status (e.g. “In review with no activity for 12 days”).
• Click-Through — Click any project row to go directly to the project detail page and take action.
• Refresh — Click the “Refresh” button on the RAG panel header to recalculate and reload all statuses.

The CPA tab on a project detail page allows you to record Cost Per Analysis entries. CPAs represent project-associated costs that sit outside the standard formulation costing model — such as retailer listing fees, regulatory certification charges, marketing spends, testing costs, or development audits.

CPA Fields

• CPA Type — Classification of the cost: Retail, Food Service, Export, Marketing, Regulatory, Testing, Development, or Other.
• Amount — The monetary value of the CPA (in the system currency).
• Description — A clear description of what the cost represents (e.g. “Woolworths listing fee Q1 2025”).
• Department / Category — Links the CPA to an organisational division and product tier for cross-project analysis.
• Development Type — The nature of the development: New Product, Reformulation, Line Extension, Cost Reduction, Repack/Re-label, or Other.
• Valid From / Valid To — Optional validity window. If Valid To is left blank, the CPA has no expiry. Expired CPAs are shown at reduced opacity with an “Expired” badge. Active CPAs with no expiry show “No Expiry”.

CPA Summary

The top of the CPA tab shows a summary row: Total Active CPA (sum of all non-expired, active entries), total entry count, active count, and expired count.

Each entry in the table has Edit and Remove actions, so you can adjust an amount, change the type, or update validity dates at any time.

The Cooking tab on a project detail page allows you to build a step-by-step list of cooking instructions for the product. These instructions are critical for food safety compliance and can be used as the basis for product labels, spec sheets, or factory Standard Operating Procedures.

Instruction Fields

• Step Number — Controls the display order. Steps are sorted ascending by step number. Numbers do not need to be consecutive — you can use gaps (e.g. 10, 20, 30) to allow easy insertion of new steps between existing ones.
• Instruction — The full text of the cooking step (e.g. “Preheat oven to 180°C. Place product on a lightly oiled baking tray”).
• Temperature (°C) — Optional target cooking temperature. Displayed in amber on the instruction card for visibility.
• Duration (minutes) — Optional cooking time in minutes. Displayed in blue on the instruction card.
• Notes — Additional food safety information (e.g. “Ensure internal temperature reaches 75°C”, “Do not reheat”).

Managing Instructions

• Adding a Step — Click “+ Add Step” in the top-right of the Cooking tab and fill in the form.
• Editing a Step — Click the “Edit” button on any step to open the edit modal with all existing values pre-filled.
• Removing a Step — Click “Remove” on any step to permanently delete it. A confirmation prompt is shown.
• Re-ordering — Update the step number on any instruction to change its position in the list.

The NPD Lifecycle Manager supports three database backends: SQLite (default for local development), PostgreSQL (recommended for production), and MSSQL. For cloud deployment, Railway is fully supported with automatic PostgreSQL provisioning.

Switching to PostgreSQL

• Via Settings UI — Go to Settings → Database Configuration, select "PostgreSQL", enter host/port/database/user/password, test the connection, and save.
• Via Environment Variable — Set DATABASE_URL=postgresql://user:pass@host:5432/dbname. This takes priority over settings UI.
• Railway Deployment — Push to GitHub, connect to Railway, add PostgreSQL plugin. Railway sets DATABASE_URL automatically. The included Procfile configures Gunicorn with Uvicorn workers.

The system provides two mechanisms for tracking project history over time:

• Costing Versions — Lightweight snapshots of the formulation and costing for scenario comparison (e.g. "Scenario A" vs "Scenario B"). Created from the Versions tab.
• Project Snapshots — Full point-in-time captures including all 9 cost/selling/margin fields, status, phase, and complete formulation. Ideal for quarterly reviews or documenting state at phase transitions. Created using the "Create Snapshot" button.
• Comparison — Click "Compare" on any snapshot to view a side-by-side comparison with differences and percentage changes for every field.

Every project shows a comprehensive 3×3 financial grid:

These fields appear on: Project Detail (3×3 grid), Projects List (key columns), Cost Analysis page (full table + M2 Report tab), Reports page (comprehensive table), and CSV exports.

Fixed vs Calculated Cost Mode

Calculated derives cost from formulation + overheads. Fixed lets you set the total cost directly (useful for contract prices or imports). Switch modes in the Costing tab.