The NPD Lifecycle Manager is an enterprise tool designed to manage the full lifecycle of New Product Development in food manufacturing. It tracks products from initial concept through formulation, costing, multi-stage approval workflows, and into production. The system provides a centralised platform for R&D teams, quality assurance, finance, and operations to collaborate on bringing new products to market.

The system is designed for food manufacturing companies and their cross-functional teams. This includes R&D and product development teams who create formulations, quality assurance teams who validate products, finance departments who manage costing and pricing, operations teams who oversee production readiness, and management who need visibility across all NPD activities.

NPD stands for New Product Development. It refers to the complete process of bringing a new product to market, from the initial idea and concept through research, formulation, testing, approval, and finally production. In food manufacturing, NPD encompasses recipe development, ingredient sourcing, cost analysis, regulatory compliance, and production scale-up.

While the NPD Lifecycle Manager is specifically designed for food manufacturing — with features like allergen tracking, shelf life management, and food-specific terminology — the core workflow engine, costing system, and approval process can be adapted for other manufacturing industries. The formulation, costing, and multi-stage approval concepts are broadly applicable to any product development process.

Navigate to the Projects page from the sidebar and click the “New Project” button. You will need to fill in the project name, description, product type, target market, target weight in grams, shelf life in days, batch size, and priority level. You should also select a workflow template and assign a creator. The project will be created in “draft” status, ready for formulation and costing.

Projects progress through several statuses: Draft is the initial state where formulation and costing are being developed. In Review means the project has been submitted and is progressing through approval workflow stages. Approved indicates all workflow stages have been signed off. Rejected means an approver has rejected the project. On Hold indicates the project is temporarily paused. Cancelled means the project has been permanently stopped. Production indicates the product has been handed over to manufacturing.

Project codes are automatically generated in the format NPD-XXXXXX, where XXXXXX is a sequence of 6 random alphanumeric characters. This ensures every project has a unique, easily identifiable reference code. You do not need to enter a project code manually — it is assigned automatically when the project is created.

You can change a project’s status using the status dropdown on the project detail page for most statuses such as draft, in review, on hold, cancelled, or production. However, you cannot manually set a project to “approved” if it has an active workflow with remaining approval stages — the project must complete all workflow approval stages first. This enforcement ensures proper sign-offs are recorded and audit trails are maintained.

To cancel a project, go to the Projects list page and click the “Cancel” button next to the project, or open the project detail page and change the status to “Cancelled” using the status dropdown. Cancelled projects are preserved in the system with their full history for audit purposes. No data is ever deleted — the project is simply marked as cancelled and can be filtered out of active views.

Department and Category provide two levels of classification for your projects. Department represents the business division (e.g., Retail, Food Service, Export). Category represents the product range or tier (e.g., Premium, Economy, Plant-Based, Organic). These fields are free-text with autocomplete from previously used values, so you can define your own hierarchy without being locked into predefined options. You can filter the projects list by department and category using the filter dropdowns.

Batch size (in kg) represents the total weight of one production batch. It is set at project creation time and is used to drive the bidirectional quantity/percentage calculation in the formulation. When you enter a quantity for an ingredient, the system automatically calculates its percentage of the batch. Conversely, when you enter a percentage, the system calculates the required quantity. This ensures accurate recipe scaling.

Yes. On the project detail page, navigate to the Images tab and click “Upload Image”. You can upload JPG, PNG, GIF, WebP, or BMP images up to 10 MB each. Each image can be assigned a type (General, Product Photo, Packaging, Label Design, Lab Result) and an optional caption. Images are stored on the server and can be removed at any time.

The Quality tab on a project detail page allows you to submit quality evaluations. Each evaluation includes an evaluation type (Quality, Sensory, Lab, Shelf Life), five sensory scores from 1–10 (Appearance, Texture, Flavour, Aroma, Overall), a pass/fail/conditional result, batch number, and notes. Evaluations are tracked chronologically and each submission creates an activity log entry for full traceability.

Open the project detail page by clicking on a project, then navigate to the Formulation tab. 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 project’s batch size. A live cost preview shows the estimated line cost. Click “Add Ingredient” to save the line. The total formulation cost updates automatically.

Each ingredient line cost is calculated as: Line Cost = Quantity × Ingredient Cost per Unit. For example, if you add 70 kg of Beef Trim at R62.50 per kg, the line cost will be R4,375.00. This calculation is performed automatically whenever you add or modify a formulation line, and the total ingredient cost is updated in real time.

When you update an ingredient’s cost per unit in the Ingredients Library, all projects that include that ingredient in their formulation are automatically recalculated. The formulation line costs, total ingredient costs, total project costs, cost per kg, cost per unit, and selling prices are all updated to reflect the new ingredient price.

The selling price is calculated using the margin-based pricing formula: Selling Price = Total Cost ÷ (1 - Margin%). For example, if your total project cost is R100 and you set a 35% margin, the selling price would be R100 ÷ (1 - 0.35) = R153.85. This ensures your desired profit margin is built into the final price.

There are six cost components for each project: Ingredients (automatically calculated from the formulation), Labour (direct labour cost), Overhead (factory overhead, utilities, equipment), Packaging (packaging materials), and Transport (delivery/logistics costs). Each component (except ingredients) can be entered in one of three modes: Full Value (total batch cost), Per kg (multiplied by batch size), or Per Unit (multiplied by units per batch). Two deductions are available: Rebate and Promo Value, which are subtracted from the gross cost. A Manufacturing Loss % can be applied as a cost multiplier (e.g. 10% loss = costs ÷ 0.9).

Each cost component (Labour, Overhead, Packaging, Transport, Rebate, Promo Value) can be entered in three modes:

Full Value — the value you enter is the total cost for the entire batch.
Per kg — the value is multiplied by the batch size in kg. For example, R5/kg on a 100kg batch = R500 total.
Per Unit — the value is multiplied by the number of units per batch (calculated from batch size and target weight). For example, R0.50/unit with 200 units/batch = R100 total.

Manufacturing Loss represents the percentage of material lost during production (evaporation, trimming, spillage, etc.). It is applied as a cost multiplier: the gross cost is divided by (1 - loss/100). For example, a 10% loss means costs are multiplied by 1.111 (1/0.9), reflecting that you need to produce more raw material to achieve the target output. Set this in the Costing tab under “Margins & Loss”.

The Secondary Margin is an additional margin applied on top of the primary selling price. This is useful for multi-tier pricing: the primary margin calculates the manufacturer’s selling price, and the secondary margin calculates the distributor or customer selling price. For example, if primary cost is R100 at 30% margin = R142.86 selling price, then a 15% secondary margin gives R168.07 secondary price.

Rebate and Promo Value are cost deductions subtracted from the gross cost before calculating the selling price. Like other cost components, they support three modes (Full Value, Per kg, Per Unit). This allows you to model volume rebates from suppliers or promotional allowances that reduce the effective product cost.

Yes. Each formulation line in the table has an “Edit” button. Clicking it opens an inline modal where you can adjust the quantity and percentage. When you save, the system recalculates the line cost and total formulation cost automatically.

Projects are assigned a workflow template that defines a series of approval stages. For example, the standard workflow includes R&D Review, QA Sign-off, Finance Approval, and Operations Sign-off. Each stage specifies the required role and number of approvals needed. When a project is submitted for review, it enters the first stage and progresses through each subsequent stage as approvals are granted. Workflow enforcement is strict — a project cannot be manually set to “approved” status while it still has pending workflow stages. It must complete all stages through the formal approval process.

No. The system enforces that every workflow stage must be completed in sequence. You cannot manually change a project’s status to “approved” if it has an active workflow with remaining stages. The “approved” option is not available in the status dropdown until all workflow stages are completed. This ensures proper governance, accountability, and audit trails for every product release.

When an approver rejects a project at any workflow stage, the project’s status changes to “rejected” and the workflow is halted. The rejection is recorded with the approver’s details. The project creator can then revise the formulation, costing, or other details before resubmitting the project for a new round of approvals.

Yes, you can create fully custom workflow templates. Navigate to the Workflow Config page from the sidebar and click “New Template”. Define the template name and description, then add stages with custom names, ordering, required roles, and required approver counts. You can also set a template as the default, which will be automatically assigned to new projects.

Auto advance is a workflow stage setting (enabled by default) that automatically moves the project to the next stage once the required number of approvals has been met. If disabled on a specific stage, a manual action is needed to progress the project. This feature streamlines the approval process by eliminating the need for someone to manually advance the workflow after all approvals are collected.

There are four user roles: Admin has full access to all features including user management, settings, and system configuration. Manager can approve workflow stages, manage projects, and view reports. User has standard access for creating and managing projects, adding formulations, and participating in workflows. Viewer has read-only access and can view projects, reports, and data but cannot create or modify anything.

Navigate to the Users page from the sidebar and click the “Add User” button. Fill in the required fields: email address, full name, role (Admin, Manager, User, or Viewer), and department. The user will be created with an active status by default and can immediately participate in workflows according to their assigned role.

Yes, you can deactivate a user by clicking the “Deactivate” button next to their name on the Users page, or by editing their profile and toggling their active status. Deactivated users cannot participate in workflows, but all their historical data — including past approvals, project ownership, and activity records — is preserved in the system. You can reactivate a user at any time. No user data is ever deleted from the system.

On first launch, if no users exist in the database, the system automatically creates a single bootstrap Admin account. By default this is email admin@company.local / password changeme, but if you set the ADMIN_EMAIL and ADMIN_PASSWORD environment variables (recommended for any deployment), those are used instead. Sign in and change the password immediately. The “First Launch Detected” hint on the login page only appears while the system still has a single admin on the default changeme password — it disappears automatically once you change the password, add another user, or boot with a custom ADMIN_PASSWORD.

Users sign in with their email and password. The system issues a JWT (JSON Web Token) that is sent with every subsequent request. Tokens expire after 24 hours. All passwords are hashed with bcrypt and never stored in plain text. Administrators create user accounts and can reset any user’s password from the Users page. Users can change their own password via the Change Password API endpoint.

All demo users (imported via the demo data system) use the password demo123. Their email addresses use the @excellentmeat.co.za domain.

The dashboard automatically hides rejected projects from the recent projects list to keep the view focused on active work. The count of rejected projects is shown in a banner above the projects section, and you can click the link to view all rejected projects on the Projects page filtered by status. The “Rejected” stat card on the dashboard still shows the total count for quick reference.

No. The NPD Lifecycle Manager is designed with a no-delete policy to ensure full auditability and data integrity. Instead of deleting records, all entities use status-based management: projects are cancelled, users and ingredients are deactivated, and workflows are deactivated. All historical data, including approvals, formulation changes, and activity logs, is permanently preserved for regulatory compliance and audit trail purposes.

Deactivated ingredients are hidden from ingredient selection dropdowns when building new formulations, but they remain in the system and any existing formulation lines that reference them continue to display correctly. This ensures historical cost data and recipe records remain accurate. You can reactivate an ingredient at any time if it becomes available again.

Demo data is a rich set of sample records — 13 projects, 39 ingredients, 5 users, allergens, constraints, departments, trials, costings, approvals, evaluations, images, cooking instructions and more — that you can import to explore every feature of the system. Manage it from the dedicated Demo page (which lists the full dataset) or from Settings → Demo Data. You can import the full dataset in one click, or seed it selectively — tick exactly which components you want (master data, individual product categories such as steaks, sausages, patties and plant-based, and per-project enrichments). Seeding is incremental: dependencies are pulled in automatically, and re-importing only adds what is missing, so you can build the dataset up in stages without duplicating anything. Removal mirrors seeding — remove everything, or tick components to remove just part of it (dependent records cascade so the result stays consistent). Removal is confirmed first, and only demo-flagged records are removed — any real data you have added alongside the demo data is preserved.

The system provides comprehensive reporting across all views:

Dashboard — Key metrics, RAG status, and recent activity overview.
Cost Analysis — Full breakdown showing Cost Value/kg/Unit, Selling Value/kg/Unit, and Margin 2 Value/kg/Unit for every project. Includes visual comparison bars, margin health analysis, and a dedicated M2 Report tab.
Reports Page — Status distribution, top projects by cost, and a comprehensive table with all 9 cost/selling/margin columns plus CSV export.
Project Detail — Per-project 3×3 grid showing Cost, Selling, and M2 values in Value/kg/Unit format.
Projects List — Table columns for Cost Value, Cost/kg, Cost/Unit, Selling, Sell/kg, and M2 Value.
All reports support filtering by status, type, department, category, and priority. CSV export is available on the Cost Analysis and Reports pages.

Yes. Open any project and click the Spec Sheet button at the top. This opens a clean, print-ready Product Specification Sheet in a new tab, consolidating the product details, formulation (or cut specification for primal products), allergen declaration, cooking instructions, and costing summary. Click Print / Save as PDF and choose your printer, or select “Save as PDF” as the destination to export a PDF. The sheet always reflects the project’s current data, so it’s ideal for QA records, customer hand-offs, and factory spec packs.

Yes. On the Ingredients page click Import CSV. Download the template for the correct format, then upload a CSV with the columns name, category, unit, cost_per_unit (and optionally supplier, code, allergens). Leave code blank to auto-generate it. The importer creates every valid row and reports any rows it skipped (duplicate codes, missing fields, invalid cost) so nothing fails silently. The file limit is 2 MB / 2000 rows.

Yes. Go to Settings → General Settings and set your Company Name and a Logo URL (either a public image URL or a /static/… path). These appear on the login page and on every Product Specification Sheet, so the system and its documents carry your organisation’s identity. A live logo preview is shown while you edit.

Yes. The Portfolio Analytics panel on the Dashboard shows a donut chart of projects by status and a bar chart of projects by lifecycle phase, alongside the RAG health panel and cost overview — giving management an immediate visual read on the pipeline.

Email notifications are automatically queued when significant events occur, such as project status changes. Notifications are addressed to all users with Admin or Manager roles, as well as the project creator. The system uses the SMTP configuration defined in the Settings page to deliver emails once configured. Until SMTP is set up, notifications are logged to the database for audit purposes. You can view the full notification history in the Email Notification Log on the Settings page.

All application settings are configurable from the Settings page. This includes general settings (application name, currency), database configuration (SQLite, PostgreSQL, or MSSQL), email/SMTP settings, and security settings (secret key). Sensitive values like passwords are encrypted at rest using Fernet encryption. Database changes require an application restart to take effect. The application also enforces CORS restrictions, security response headers (X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy), and strict input validation on all API endpoints via Pydantic schemas.

Recipe Products are batch-based formulations (sausages, patties, mince, plant-based products, marinades). They use a batch size in kg, with ingredients measured in quantities and percentages.

Primal Products are cut-based products (steaks, chops, fillets, roasts). Instead of a formulation, they define cut weight (g), cut thickness (mm), pieces per batch, the primal source (e.g. Beef Loin), and yield percentage. The system calculates total raw material requirements and waste based on yield.

Every project progresses through four phases: Development (initial creation), Trial (small controlled batch), Scale-Up (larger batch with full testing), and Production (full rollout). At each phase transition, the workflow resets and all approval stages must be completed again.

For recipe products, you can pre-plan batch sizes for each phase (e.g. Dev: 100 kg, Trial: 250 kg, Scale-Up: 500 kg, Production: 1000 kg). When the project advances to a new phase, the batch size updates automatically. Phase batch sizes can be edited from the Costing tab.

Automatic: When all workflow approval stages are completed, the system advances to the next phase and resets the workflow.
Manual: Click "Advance to [Next Phase]" on the project detail page when no workflow stages are pending.

Departments represent organisational divisions (e.g. Sausages, Steaks, Plant-Based). Each department can be linked to a specific workflow template. When a project is created with a department, the department’s workflow template is automatically assigned to the project, ensuring consistent approval processes per department. Departments are managed from the Departments page.

Navigate to the Departments page from the sidebar. Click “Add Department” to create a new department with a name, description, and optional default workflow template. Use the table to view, edit, activate, or deactivate departments. Each department can be linked to a workflow template, so projects assigned to that department automatically inherit the correct approval process.

The system maintains a managed list of allergens (e.g. Gluten, Soy, Dairy, Egg, Nuts). Each ingredient can be linked to multiple allergens using checkboxes on the Ingredients page. When viewing a project, the system automatically detects all allergens present in the formulation and displays warning banners with allergen badges. This helps ensure regulatory compliance and proper labelling.

Operational Constraints represent production sequencing requirements and cross-contamination risks (e.g. “Contains pork — requires dedicated line”, “Strong flavourant — line flush required”). Constraints are linked to ingredients, and when a project uses those ingredients, warning banners are displayed on the project detail page showing which constraints apply and their severity level.

Navigate to the Allergens page from the sidebar. Click “Add Allergen” to create a new allergen with a name, code, and optional description. Use the table to view, edit, activate, or deactivate allergens. The search bar and active/inactive filter help you find specific allergens quickly. Allergens are linked to ingredients via checkboxes on the Ingredients page.

Navigate to the Constraints page from the sidebar. Click “Add Constraint” to create a new constraint with a name, type (Flavourant, Allergen Cross, Cleaning Required), severity (Warning, Critical), and optional description. Use the table to view, edit, activate, or deactivate constraints. Filters for search, type, severity, and active status are provided.

When creating an ingredient, the code field is optional. If left blank, the system generates a code based on the ingredient’s category with a random 4-digit suffix (e.g. MEAT-3847, SPICE-1294). Category prefixes include MEAT, SPICE, CAS, ADD, PKG, PRES, FLAV, FILL, PB, FAT, PADD, WAT, and OTHER. You can always provide a custom code if preferred.

On the project detail page, navigate to the Trials tab and click “Record Trial”. Enter the batch number, trial date (defaults to today), input batch size (kg), output quantity (kg), pass/fail result, and optional notes. The “Recorded By” field is automatically populated with your logged-in user name. The system automatically calculates yield percentage and waste (kg). Each trial card shows the batch details plus its associated additional costs. Each trial is logged in the activity timeline.

On the Trials tab, each trial batch card has a “+ Add Cost” button. Click it to open the cost entry modal and select a cost type (Materials, Labour, Testing/Lab, Equipment, Transport, Packaging, Overhead, or Other), enter an amount, and provide a description. You can add as many cost entries as needed per trial. The total is displayed on the trial card, along with an actual cost per kg based on the trial’s real output — allowing direct comparison against the formulation cost model.

The By-Products tab tracks secondary outputs from production. By-products (non-waste) represent recoverable materials with commercial value — their cost value is deducted from the project’s total cost. Waste items are tracked for accounting purposes but do not affect cost calculations. Each item can have a name, weight (kg), piece count, cost value, and cost mode (Full Value, Per kg, Per Unit). Click the “Edit” button on any by-product row to modify its details inline. Changes automatically trigger a full cost recalculation. This is especially useful for primal cut projects where trim and offcuts have resale value.

The Versions tab allows you to snapshot the current costing at any point for comparison. Click “Snapshot Current Costing”, enter a name (e.g. “Scenario A”, “Rev 2”), and the system saves a complete copy of all cost components, selling prices, margins, and the full formulation. This enables side-by-side comparison of different costing scenarios across the project’s lifecycle.

Yield calculations are bidirectional. If you enter cut weight and pieces per batch, the system calculates yield percentage from (cut_weight × pieces) ÷ batch_size. Conversely, if you enter yield percentage, the system calculates pieces from (batch_size × yield) ÷ cut_weight. The yield analysis section shows raw material needed per cut, waste per cut, and total raw material requirements.

A CPA (Cost Per Analysis) entry represents an additional cost associated with a project that falls outside the standard formulation costing model — for example, a retailer listing fee, a regulatory certification cost, a marketing spend, or a testing/audit charge. CPAs are recorded on the CPA tab of each project. They are classified by type (Retail, Food Service, Export, Marketing, Regulatory, Testing, Development, Other) and can be linked to a department, category, and development type for reporting and budgeting purposes.

Every CPA entry can have an optional Valid From and Valid To date. If Valid To is left blank, the CPA has no expiry and remains active indefinitely. If a Valid To date is set and that date has passed, the entry is marked as Expired and shown at reduced opacity in the CPA table. The CPA summary shows counts of active, expired, and total entries, as well as the total value of currently active (non-expired) CPAs.

The Development Type field classifies the type of NPD work the CPA is associated with: New Product, Reformulation, Line Extension, Cost Reduction, Repack / Re-label, or Other. This allows you to segment CPA costs by the nature of the development project when reporting across departments or categories.

Cooking Instructions are step-by-step preparation guidelines stored against each project on the Cooking tab. They are critical for food safety compliance — specifying the correct temperatures and cooking durations ensures that products reach safe internal temperatures and meet regulatory requirements. Each step can include a target temperature in °C and a duration in minutes, making them suitable for use on product labels, spec sheets, or factory Standard Operating Procedures (SOPs).

On the project detail page, open the Cooking tab and click “+ Add Step”. Fill in the step number, instruction text, optional temperature (°C), optional duration (minutes), and any food safety notes. Steps are displayed in step-number order with numbered circles. Use the Edit button on any step to update it, or Remove to delete a step. Step numbers can be set freely — assign 1, 2, 3, etc. to build a sequential guide, or use non-sequential numbers to represent grouped stages.

Cooking instructions are optional but strongly recommended for food safety compliance. They provide a documented, repeatable process for each product that can be referenced during production, audits, and quality checks.

The RAG (Red / Amber / Green) Status panel on the main dashboard gives an at-a-glance health check of your entire NPD portfolio. Each project is automatically assigned a colour:

Green — Healthy and on track: projects that are approved, in production, actively in review (<7 days), or in early draft.

Amber — Needs attention: projects on hold (normal priority), drafts not progressed in 30+ days, or reviews stalled for 7+ days.

Red — Requires immediate action: rejected projects, cancelled projects, high/critical priority projects on hold, or critical priority projects stalled in review for 14+ days.

Click any of the three coloured buttons (Green, Amber, Red) at the top of the RAG panel to filter the project list below to show only projects of that status. Click the “All” button to return to showing all projects. The filter highlights the active selection with an outline. Each row in the list is clickable and links directly to the project detail page for immediate action.

No — RAG status is calculated automatically based on objective criteria: project status, priority level, and the number of days since the last update. To change a project’s RAG status, take action on the project itself: progress it through a workflow stage, change its status, update it to reset the activity timer, or change its priority. The RAG panel updates each time you click Refresh on the dashboard.

Yes. The system supports three database backends: SQLite (default, file-based, ideal for local development), PostgreSQL (recommended for production and cloud deployment), and MSSQL (for Microsoft SQL Server environments). To switch to PostgreSQL, go to Settings → Database Configuration, select “PostgreSQL”, enter your connection details, test the connection, and save. Alternatively, set the DATABASE_URL environment variable to your PostgreSQL connection string.

Railway is a cloud platform for deploying web applications. To deploy the NPD Lifecycle Manager:

1. Push your code to a GitHub repository.
2. Create a new project in Railway and connect your repo.
3. Add a PostgreSQL plugin in Railway — the DATABASE_URL is set automatically.
4. Set any additional environment variables (e.g. SECRET_KEY, BASE_URL).
5. Railway will detect the Procfile and deploy using Gunicorn with Uvicorn workers.

The app automatically detects Railway-style postgres:// URLs and converts them to the correct postgresql:// format.

This almost always means the app is still running on SQLite instead of your PostgreSQL database. On an ephemeral host the SQLite file is wiped on every redeploy, so the database is empty each boot and you see the first-launch hint again.

How to confirm: open Settings → Database Configuration — the banner at the top shows the database the app is actually connected to right now (and where the setting came from). You can also check the deploy logs for the line Database backend: … printed at startup.

How to fix:

• Make sure DATABASE_URL is set on the app service, not only on the Postgres service. In Railway, add a variable on your app that references the database, e.g. DATABASE_URL = ${{ Postgres.DATABASE_URL }}.
• Alternatively, the app will also build the connection from the standard PGHOST, PGPORT, PGUSER, PGPASSWORD, and PGDATABASE variables if DATABASE_URL isn’t present.
• Setting the database via the Settings UI does not persist on Railway (the config file is ephemeral) — use environment variables for cloud deployments.
• Set ADMIN_EMAIL / ADMIN_PASSWORD so the bootstrap admin uses your credentials (not the changeme default), and set a fixed SECRET_KEY so sessions survive redeploys.
• Redeploy after changing variables — connection settings are read at startup.

Project Snapshots capture a complete point-in-time record of a project’s cost, selling, and margin data. Unlike Costing Versions (which capture formulation scenarios), snapshots store the full project state including status, phase, all 9 cost/selling/margin fields, and the complete formulation. Snapshots are ideal for quarterly reviews, pre/post price changes, or documenting the state at each phase transition.

On the project detail page, go to the Versions tab. Under “Project Snapshots”, click the “Compare” button next to any snapshot. Select another snapshot to compare against. The system displays a side-by-side comparison of all cost, selling, and margin fields with calculated differences and percentage changes.

Calculated (default) — Total cost derived from formulation ingredients plus overheads.
Fixed — You set the total cost directly. Per-kg and per-unit values are calculated from your fixed cost. Switch between modes in the Costing tab.

Cost Value / Cost/kg / Cost/Unit — Production cost metrics.
Selling Value / Selling/kg / Selling/Unit — Primary margin selling prices.
M2 Value / M2/kg / M2/Unit — Secondary margin (distributor/customer) values.

Margin 2 is applied on top of the M1 selling price. M2 Selling = M1 Selling ÷ (1 − M2%/100). M2 Value = M2 Selling − M1 Selling. For example: M1 selling R100, M2 20% = M2 selling R125, M2 value R25.

Yes. Product types use SA standard names including Boerewors, Droëwors, Biltong, Polony, Vienna, Frankfurter, Sosatie, and Kebab. Primal cuts use SA classifications (Forequarter, Hindquarter, Loin, Fillet, Rump, Rib, Chuck, Sirloin, Brisket, Shin, Flank, T-Bone, Topside, Silverside). Currency defaults to ZAR (R).

Every mutation to a project is recorded with a timestamp: field changes (with old → new values), formulation additions/updates/removals, image uploads and deletions, by-product changes, trial results, CPA entries, cooking instruction edits, costing version snapshots, project snapshots, status changes, approval decisions, phase advancements, and manual comments. Each entry shows who made the change and when.

Open any project and switch to the Activity tab. The timeline displays all events in reverse chronological order (newest first), with colour-coded icons per event type — purple for field edits, cyan for formulation changes, green for images, amber for phase changes, etc.

The timeline currently shows all events for the project. You can scroll through the full history. Each event is categorised by type (system, comment, approval, status_change) to help you find specific entries.

Recipe mode is for formulated products (sausages, patties, mince) where you define ingredients with quantities and percentages. The batch size is the total formulation weight.

Primal mode is for cut-based products (steaks, chops, fillets) where you define the source primal, individual cut weight, thickness, and pieces per batch. Yield is calculated automatically from input weight versus output cuts.

Yield % = (Cut Weight × Pieces per Batch) ÷ (Batch Size × 1000) × 100. The system auto-calculates yield when you set cut weight, pieces, and batch size. You can also set yield directly and the system will calculate the number of pieces.

Yes. Primal processing generates offcuts (fat trim, bone, sinew) that may have recovery value. Add by-products in the By-Products tab. Mark sellable items as “By-Product” (their value is deducted from total cost) and non-sellable items as “Waste” (tracked but no cost impact).

A Costing Version captures the current cost scenario (ingredient costs, overheads, margins, formulation) as a numbered revision (e.g. “Scenario A”, “Rev 2”). Use it for what-if analysis and cost comparison between different pricing strategies.

A Project Snapshot captures the entire project state (status, phase, all costs, selling prices, formulation) at a point in time. Use it for historical record-keeping, phase transition milestones, or regulatory documentation.

In the Versions tab, each snapshot has a “Compare” option. Select any two snapshots or costing versions to view a side-by-side comparison of all cost components, selling prices, margins, and formulation differences.

Best practice is to snapshot before major changes: before phase advancement, before price reviews, before formulation changes, and at quarterly milestones. The system also automatically records phase advancement events in the Activity log.

The interface is built with standard, modern web technologies and works in current versions of Chrome, Edge, Firefox, and Safari on desktop, tablet, and mobile. The layout is fully responsive — the sidebar collapses to a menu on smaller screens. The app is also installable as a Progressive Web App (PWA) from supported browsers for an app-like experience.

For the default SQLite backend, the entire database is a single file (npd_lifecycle.db) — copy it while the app is stopped (or use SQLite’s online backup) for a full backup. For PostgreSQL or MSSQL, use your provider’s standard backup tooling (e.g. pg_dump, or automated managed backups on Railway/cloud). Uploaded project images live in frontend/static/uploads/ and should be backed up alongside the database. Because the system follows a no-delete policy, your audit history is preserved within the database itself.

Yes. Key columns (status, phase, codes, foreign keys, and the demo flag) are indexed for fast filtering and lookups. For light single-team use, SQLite is sufficient; for larger teams, concurrent editing, and higher volumes, switch to PostgreSQL via Settings → Database Configuration or the DATABASE_URL environment variable. PostgreSQL is recommended for any multi-user production deployment.

Authentication uses JWT tokens with bcrypt-hashed passwords. Privileged actions (user management, settings, and the demo / clear-all endpoints) require an admin account. Sensitive settings values are encrypted at rest with Fernet, and the API enforces CORS, security response headers, and strict Pydantic input validation on every endpoint. For production, always set a fixed SECRET_KEY, change the default admin password immediately, and run with ENVIRONMENT=production (which disables the interactive API docs).