### Mix Calculator — Clean Feature Spec

# Purpose
The Mix Calculator allows authorised users to calculate the raw materials required for a client-specific product mix, based on a selected client, product, date, and batch size.

It should also keep a history of each calculation session so users can review previous mixes without storing generated PDFs in the database.

# Core Workflow

- User opens Mix Calculator from the sidebar.
User enters/selects:
- Mix date (Defaults to today's date)
- Client
- Product - These should be populated from our existing products for that specific client
- Specify Batch size in kilograms
Total number of bags
Staff name / prepared by
App filters available products based on the selected client.
User selects a product.
App calculates:
Required raw materials
Required mix quantities
Total kilograms
Bag quantity details
User can save the session.
User can generate a polished PDF on demand.
Sidebar

# Add a dedicated sidebar item:

Mix Calculator

This should be separate from costing, product setup, or admin areas.

# Permissions
Create a dedicated permission area:

mix_calculator:view
mix_calculator:create
mix_calculator:edit
mix_calculator:delete
mix_calculator:generate_pdf
mix_calculator:view_all_sessions

# Suggested roles:

Role	Access
Admin	Full access
Manager	Create, view all, generate PDFs
Staff	Create, view own sessions, generate PDFs
Viewer	View only
Database Naming

Avoid the table name mix-calculator because hyphens are awkward in SQL and code.

Use:

mix_calculator_sessions

Optional supporting tables:

clients
products
product_mixes
raw_materials
mix_calculator_session_lines
Suggested Tables
mix_calculator_sessions

Stores each calculator run.

id
session_number
client_id
product_id
mix_date
batch_size_kg
total_bags
total_kg
prepared_by_user_id
prepared_by_name
created_at
updated_at
created_by
status
notes
mix_calculator_session_lines

Stores calculated raw material outputs for each session.

id
session_id
raw_material_id
raw_material_name
required_kg
mix_percentage
unit
sort_order

This allows historical sessions to remain accurate even if the product recipe changes later.

PDF Behaviour

PDFs should not be stored in the database.

Instead:

Generate PDF on demand from the saved session.
Use the saved session and session lines as the source.
Allow download as:
MixCalculator_{Client}_{Product}_{Date}_{SessionNumber}.pdf

PDF should include:

Date
Client
Product
Batch size
Total kilograms
Total bags
Prepared by / staff name
Raw material table
Required mix table
Session number
Generated timestamp
Feature Name Options

Recommended:

Mix Calculator

Other options:

Batch Mix Calculator
Production Mix Calculator
Client Mix Calculator
Mix Session Calculator

Best fit: Mix Calculator.

Clean Requirement Summary

Build a dedicated Mix Calculator module that allows authorised users to create client-specific mix calculation sessions. Users select a date, client, product, batch size, total bags, and staff name. The system calculates required raw materials and mix quantities, saves the session history, and allows users to generate a polished PDF on demand. PDFs should not be stored in the database; they should be generated dynamically from the saved session data.