## Repository operations

### Dependencies

Current app dependency entry points:

| Area | File | Notes |
| --- | --- | --- |
| Frontend runtime + tooling | `frontend/package.json` | SvelteKit app, Vite build, Vitest tests |
| Frontend lockfile | `frontend/package-lock.json` | Generated by npm, commit this with dependency changes |
| Backend runtime + tooling | `backend/pyproject.toml` | FastAPI app, SQLAlchemy, pytest, packaging metadata |

Current declared dependencies:

#### Frontend

- Runtime: `lucide-svelte`
- Dev/build: `@sveltejs/adapter-auto`, `@sveltejs/adapter-node`, `@sveltejs/kit`, `svelte`, `typescript`, `vite`, `vitest`

#### Backend

- Runtime/tooling: `fastapi`, `openpyxl`, `rich`, `uvicorn[standard]`, `sqlalchemy`, `pydantic`, `psycopg[binary]`, `reportlab`
- Test dependency: `pytest`

### Dependency update workflow

Use a small, controlled update flow rather than bulk-upgrading everything immediately before production.

#### Frontend

Check what is outdated:

```bash
cd frontend
npm outdated
```

Install targeted upgrades:

```bash
npm install <package>@latest
```

For a broader refresh within `package.json` ranges:

```bash
npm update
```

Then verify:

```bash
npm run test
npm run build
```

#### Backend

Check current declared versions in:

```bash
backend/pyproject.toml
```

Upgrade by editing version ranges in `backend/pyproject.toml`, then reinstall:

```bash
cd backend
pip install -e .
pytest
```

If a backend dependency is high-risk near production, prefer upgrading one package at a time and re-running API tests after each change.

### Repository hygiene

The repo should keep source code and deployment assets, but not generated local artifacts.

Expected long-lived top-level folders:

- `backend/`
- `frontend/`
- `deploy/`

Expected long-lived top-level docs/config files:

- `README.md`
- `CLAUDE.MD`
- `docker-compose*.yml`
- `.env*.example`

Files that should stay out of version control or be moved out of the project root over time:

- SQLite databases such as `data_entry_app.db`
- local cache folders such as `.pytest_cache/` and `pytest-cache-files-*`
- virtual environments such as `.venv/`
- one-off working assets such as loose spreadsheets, image exports, or temporary notes unless they are intentional project deliverables

### Tests and pytest files

There are not many real pytest source files in this repo right now.

Current actual backend tests:

- `backend/tests/test_access.py`
- `backend/tests/test_costing_engine.py`

Most of the extra `pytest`-named items are generated cache/temp directories from local test runs, not hand-written test suites.

## Spreadsheet analysis summary

The workbook is effectively a costing and pricing model with three core calculation layers:

### 1. Raw Materials

Sheet: **`C- Raw Products Costs`**

Table: **`StraightGrain`**

This is the base input table.

Main fields:

| Area | Purpose |
| --- | --- |
| Raw Materials | Ingredient / material name |
| Market Value Uncleaned Grain | Base cost |
| Unit of Measure | kg, per tonne, bag, etc. |
| Kg per unit of measure | Converts purchase unit into kg |
| Waste % of Loss | Loss / shrinkage assumption |
| Loss | Formula-driven cost loss |
| Cost per Unit of Measure | Base cost + loss |
| Cost per Kg | Final reusable cost input |

Core formula pattern:

```
Loss = Market Value * Waste %
Cost per Unit = Loss + Market Value
Cost per Kg = Cost per Unit / Kg per Unit
```

This should become the foundation table in the app, with price history and versioning.

---

### 2. Mix Master

Sheet: **`M - All`**

Table: **`AllMix`**

This is the recipe / bill-of-materials table.

Main purpose:

| Area | Purpose |
| --- | --- |
| Client | Product/customer grouping |
| Product | Mix name |
| Total KGs per mix | Formula sum of all ingredients |
| Ingredient columns | Quantity of each raw material in the mix |
| Mix cost section | Calculates cost per mix and cost per kg |

Core formula pattern:

```
Total KGs per mix = SUM(all ingredient quantities)

Ingredient Cost = Ingredient Quantity * Raw Material Cost per Kg

Total Mix Cost = SUM(all ingredient costs)

Mix Cost per Kg = Total Mix Cost / Total KGs per mix
```

This should become a structured recipe module, not a wide spreadsheet table. In the app, each mix should have many ingredient rows rather than 60+ ingredient columns.

Important workbook comments found here:

| Location | Comment |
| --- | --- |
| `M - All!B8` | Need to confirm recipe |
| `M - All!D10` | Mix is 280, but bulka fits 550, therefore 275 for 2 batches |
| `M - All!AB53` | 85 same as Mayreef, was 110 according to files |

These should become data-quality notes or review flags in the app.

---

### 3. Product / Unit Cost / Price

Sheet: **`Product Cost - Price`**

Table: **`ProductCost`**

This is the main output table.

Main fields:

| Area | Purpose |
| --- | --- |
| Client | Pricing group |
| Item ID | Xero/product identifier |
| Name | Product name |
| Mix / Product Name | Links back to Mix Master |
| Standard or Bulka | Packaging / sale type |
| Own Bag | Packaging logic |
| Std Unit of Measure | Usually kg, bag, tonne, etc. |
| Items Per Pallet | Used in freight calculations |
| Bagging Process | Determines process costs |
| Distributor / Wholesale | Target margin inputs or outputs |
| Cleaned Product | Mix cost pulled from `M - All` |
| Grading / Bagging / Cracking | Process costs |
| Bag Cost | Packaging cost logic |
| Freight Cost | Freight allocation |
| Finished Product Delivered | Final delivered product cost |
| Price columns | Distributor and wholesale selling price outputs |

Core calculation pattern:

```
Cleaned Product = Mix Cost per Kg

Process Cost = Grading + Bagging + Cracking

Packaging Cost = Based on Standard / Bulka / Own Bag / Bag Size

Freight Cost = Based on pallet, kg, product type, or special case

Finished Product Delivered =
    Cleaned Product
    + Process Cost
    + Packaging Cost
    + Freight Cost

Selling Price =
    Finished Product Delivered / (1 - Margin)
```

Important workbook comments found here:

| Location | Comment |
| --- | --- |
| `Product Cost - Price!R4` | 20kg bag or by KG if Ton |
| `Product Cost - Price!X14` | Includes 24% profit. Cost per tonne $68 |
| `Product Cost - Price!C50` | In OLD - Ian McKay Stock Mix 20kg |

These should also become structured notes / flags.

---

## Recommended app direction

Build the app around **controlled costing scenarios**, not just data entry.

The client should enter raw material prices, recipes, product settings, packaging assumptions, freight costs, and margin rules. The backend should calculate final unit cost and pricing outputs. Power BI should consume clean, flattened API/database views.

The most important design decision:

> The spreadsheet formulas should move into the FastAPI backend, not the Svelte frontend.
> 

The frontend should display inputs, validation warnings, scenario comparisons, and results. The backend should own the calculation engine, audit trail, versioning, and API outputs.

---

# Proposed system architecture

```
Svelte App
  |
  |-- Client Portal
  |     |-- Manage raw materials
  |     |-- Manage mix recipes
  |     |-- Manage products
  |     |-- Run price simulations
  |     |-- Submit / approve changes
  |
  |-- Consultancy/Admin Portal
        |-- Review client changes
        |-- Manage assumptions
        |-- Compare scenarios
        |-- Export / publish to Power BI
        |-- Audit history

FastAPI Backend
  |
  |-- Auth + tenant access
  |-- Data validation
  |-- Cost calculation engine
  |-- Scenario/version control
  |-- Xero item mapping
  |-- Power BI API endpoints
  |-- Audit logging

Database
  |
  |-- PostgreSQL recommended
  |-- SQLite acceptable only for prototype
```

---

# Core modules

## 1. Authentication and tenancy

Because this is consultancy-built software for a client, the app should support separation between:

| Role | Access |
| --- | --- |
| Client User | Enter and update data |
| Client Manager | Approve changes and scenarios |
| Consultancy User | Review, correct, simulate, publish |
| Admin | Manage users, assumptions, integrations |

Even if there is only one client at launch, build with `tenant_id` from the start.

---

## 2. Raw Materials module

This replaces **`C- Raw Products Costs`**.

### Required features

The client should be able to manage:

| Field | Notes |
| --- | --- |
| Raw Material Name | e.g. Maize, Barley, Acid Buf |
| Supplier / Xero Item | Optional but useful |
| Market Value | Main editable price input |
| Unit of Measure | kg, tonne, 20kg bag, etc. |
| Kg per Unit | Used for conversion |
| Waste % / Loss % | Editable assumption |
| Effective Date | Required for price history |
| Status | Draft, Active, Archived |
| Notes | For exceptions |

### Backend calculation

```
loss_cost = market_value * waste_percentage

cost_per_unit = market_value + loss_cost

cost_per_kg = cost_per_unit / kg_per_unit
```

### Key requirement

Do not overwrite old prices. Store price versions.

Example tables:

```
raw_materials
raw_material_price_versions
```

This allows Power BI to show price movement over time.

---

## 3. Mix Master module

This replaces **`M - All`**.

The spreadsheet has a wide format, where each raw material is a column. The app should use a proper relational structure.

### Instead of this

```
Product | Maize | Wheat | Barley | Canola | ...
```

### Use this

```
Mix
  - Mix Name
  - Client
  - Status
  - Version

Mix Ingredients
  - Mix ID
  - Raw Material ID
  - Quantity Kg
```

### Required features

| Feature | Purpose |
| --- | --- |
| Mix list | View all current mixes |
| Mix detail page | Edit ingredient quantities |
| Ingredient search | Add raw materials easily |
| Auto total kg | Sum all ingredient quantities |
| Cost per kg | Calculated by backend |
| Recipe validation | Flag missing costs or unusual quantities |
| Versioning | Compare current vs proposed recipe |
| Notes / review flags | Capture comments like “need to confirm recipe” |

### Backend calculation

```
ingredient_cost = ingredient_quantity_kg * raw_material_cost_per_kg

total_mix_cost = SUM(ingredient_cost)

total_mix_kg = SUM(ingredient_quantity_kg)

mix_cost_per_kg = total_mix_cost / total_mix_kg
```

---

## 4. Product Cost / Unit Cost module

This replaces **`Product Cost - Price`**.

This is the main commercial output of the app.

### Product setup fields

| Field | Source |
| --- | --- |
| Client | Existing spreadsheet |
| Item ID | Xero / product system |
| Name | Product name |
| Mix / Product Name | Links to Mix Master |
| Standard or Bulka | Pricing logic |
| Own Bag | Packaging logic |
| Unit of Measure | Pricing logic |
| Items Per Pallet | Freight logic |
| Bagging Process | Process cost lookup |
| Distributor Margin | Pricing rule |
| Wholesale Margin | Pricing rule |

### Cost output fields

| Output | Logic |
| --- | --- |
| Cleaned Product Cost | From Mix Master |
| Grading Cost | From process assumptions |
| Bagging Cost | From process assumptions |
| Cracking Cost | From process assumptions |
| Bag Cost | From packaging assumptions |
| Freight Cost | From freight assumptions |
| Finished Product Delivered | Sum of above |
| Distributor Price | Cost / margin |
| Wholesale Price | Cost / margin |

### Backend calculation engine

Create a dedicated backend service:

```
/app/services/costing_engine.py
```

Suggested calculation order:

```
1. Load product
2. Load linked mix
3. Calculate mix cost per kg
4. Apply process costs
5. Apply packaging costs
6. Apply freight costs
7. Calculate finished delivered cost
8. Apply distributor / wholesale margins
9. Return full calculation breakdown
```

Every calculated product should return a transparent cost build-up.

Example output:

```
{
  "product_id":123,
  "cleaned_product_cost":0.5444,
  "grading_cost":0.055,
  "bagging_cost":0.04,
  "cracking_cost":0,
  "bag_cost":0.63,
  "freight_cost":1.45,
  "finished_product_delivered":14.31,
  "distributor_price":18.46,
  "wholesale_price":null,
  "warnings": []
}
```

---

## 5. Assumptions module

The spreadsheet has embedded assumption tables around process costs, packaging costs, freight costs, and margins. These should not remain hidden in formulas.

Create editable assumption tables for:

| Assumption type | Examples |
| --- | --- |
| Process costs | Grading, cracking, bagging |
| Packaging costs | 20kg bag, bulka bag, wrap, slip sheet |
| Freight costs | Freight per pallet, special freight rules |
| Margin rules | Distributor / wholesale margin by client/category |
| Special cases | Peckish, Hay & Straw, PHF Horse Mixes |

This is important because the current workbook has hardcoded special logic in formulas. In the app, these rules should be visible and maintainable.

---

## 6. Scenario and simulation module

This is one of the most important parts based on your notes.

The client needs to simulate and negotiate prices. That means the app should support scenarios.

### Scenario examples

| Scenario | Purpose |
| --- | --- |
| Current Standard | Approved live pricing |
| Proposed Raw Material Increase | Test new input costs |
| Supplier Price Change | Test new Xero prices |
| Recipe Change | Change mix ingredients |
| Margin Negotiation | Test distributor/wholesale changes |
| Freight Increase | Test operational cost changes |

### Scenario workflow

```
Create Scenario
  ↓
Choose baseline
  ↓
Modify raw costs / mix / margins / freight
  ↓
Run calculation
  ↓
Compare against current
  ↓
Review margin impact
  ↓
Approve or reject
  ↓
Publish to reporting layer
```

### Comparison outputs

The UI should show:

| Comparison | Example |
| --- | --- |
| Old cost vs new cost | `$14.31 → $15.02` |
| Old price vs new price | `$18.46 → $19.38` |
| Margin impact | `22.5% → 21.1%` |
| Product impact | Which SKUs changed most |
| Raw material impact | Which ingredient caused the increase |

---

# Suggested database model

## Core tables

```
tenants
users
roles

clients
xero_items

raw_materials
raw_material_price_versions

mixes
mix_versions
mix_ingredients

products
product_versions

process_cost_rules
packaging_cost_rules
freight_cost_rules
margin_rules

costing_scenarios
costing_scenario_items
costing_results

stock_take
sales_history

data_quality_notes
audit_log
```

---

## Key relationships

```
raw_materials
  → raw_material_price_versions

mixes
  → mix_versions
  → mix_ingredients
  → raw_materials

products
  → product_versions
  → mixes

costing_scenarios
  → costing_results
  → products
```

---

# Svelte app plan

## Main navigation

```
Dashboard
Raw Materials
Mix Master
Products / Unit Costs
Scenarios
Price Review
Xero Mapping
Power BI Outputs
Admin
```

---

## 1. Dashboard

Purpose: high-level control view.

Show:

| Card | Purpose |
| --- | --- |
| Raw materials missing cost | Data quality |
| Mixes needing review | Recipe quality |
| Products with calculation warnings | Pricing quality |
| Latest approved scenario | Reporting state |
| Products changed since last publish | Governance |
| Average cost movement | Commercial insight |

---

## 2. Raw Materials page

Views:

```
Raw Materials List
Raw Material Detail
Price History
Bulk Upload
```

Features:

| Feature | Notes |
| --- | --- |
| Editable cost inputs | Market value, unit, kg conversion, waste |
| Price history | Required |
| Import from CSV/Xero | Future or phase 2 |
| Validation | Missing unit, zero kg, missing cost |
| Notes | Capture exceptions |

---

## 3. Mix Master page

Views:

```
Mix List
Mix Detail
Recipe Editor
Mix Cost Breakdown
Version Comparison
```

Recipe editor should feel like a clean table:

| Ingredient | Qty KG | Cost/KG | Line Cost | Notes |
| --- | --- | --- | --- | --- |

Footer:

```
Total KG
Total Cost
Cost per KG
Warnings
```

Validation examples:

| Warning | Reason |
| --- | --- |
| Missing raw material cost | Cannot calculate |
| Total kg is zero | Invalid recipe |
| Ingredient has no active price | Stale input |
| Recipe changed from approved version | Needs review |
| Comment unresolved | User needs to confirm |

---

## 4. Product / Unit Cost page

Views:

```
Product List
Product Detail
Cost Build-Up
Price Output
Margin Review
```

Product detail should show a transparent cost stack:

```
Cleaned Product Cost
+ Grading
+ Bagging
+ Cracking
+ Bag Cost
+ Freight Cost
= Finished Product Delivered

Then:

Distributor Price
Wholesale Price
Retail Price, if required
```

This is where the app becomes more useful than the spreadsheet.

---

## 5. Scenario page

Views:

```
Scenario List
Create Scenario
Scenario Workspace
Scenario Comparison
Approval View
```

Scenario workspace should allow the user to adjust:

| Input | Example |
| --- | --- |
| Raw material prices | Maize increases by 8% |
| Waste/loss assumptions | Waste from 2% to 4% |
| Mix ingredients | Change kg in recipe |
| Process costs | Bagging cost increase |
| Freight | New freight per pallet |
| Margin | Distributor margin change |

Output:

```
Before / After
Cost impact
Price impact
Margin impact
Products affected
Exportable result set
```

---

## 6. Price Review page

This replaces **`Price Review 30082025`**.

Purpose:

Compare old prices, proposed prices, and review status.

Suggested columns:

| Product | Current Wholesale | Proposed Wholesale | Difference | Current Distributor | Proposed Distributor | Difference | Status |
| --- | --- | --- | --- | --- | --- | --- | --- |

Statuses:

```
Draft
Reviewed
Approved
Rejected
Manual Override
Needs Client Review
```

---

## 7. Xero Mapping page

Because the raw material and product costs need to be tracked against Xero/product data, create a mapping layer.

Fields:

| Field | Purpose |
| --- | --- |
| Xero Item ID | External system key |
| SKU | Product code |
| Product Name | User-facing |
| Local Product ID | Internal app product |
| Last synced date | Data freshness |
| Sync status | Matched / unmatched / conflict |

Phase 1 can use CSV import/export.

Phase 2 can use Xero API integration.

---

## 8. Power BI Outputs page

This should expose the data model in a clean reporting shape.

Power BI should not ingest messy operational tables directly. Create purpose-built API endpoints or database views.

Recommended reporting outputs:

```
vw_raw_material_costs_current
vw_raw_material_cost_history
vw_mix_costs_current
vw_mix_ingredients_current
vw_product_costs_current
vw_product_price_outputs
vw_scenario_comparison
vw_price_review_status
vw_data_quality_issues
```

Power BI can ingest either:

```
FastAPI JSON endpoints
```

or

```
PostgreSQL views
```

For reliability, PostgreSQL views are better if Power BI can connect to the database securely.

---

# FastAPI backend plan

## Suggested backend structure

```
/backend
  /app
    main.py
    /api
      raw_materials.py
      mixes.py
      products.py
      scenarios.py
      costing.py
      imports.py
      powerbi.py
      admin.py
    /models
      raw_material.py
      mix.py
      product.py
      scenario.py
      costing_result.py
      user.py
    /schemas
      raw_material.py
      mix.py
      product.py
      scenario.py
      costing.py
    /services
      costing_engine.py
      scenario_engine.py
      import_excel.py
      xero_mapping.py
      validation.py
      audit.py
    /db
      session.py
      migrations
```

---

## Key API endpoints

### Raw materials

```
GET    /api/raw-materials
POST   /api/raw-materials
GET    /api/raw-materials/{id}
PATCH  /api/raw-materials/{id}
POST   /api/raw-materials/{id}/prices
GET    /api/raw-materials/{id}/price-history
```

### Mixes

```
GET    /api/mixes
POST   /api/mixes
GET    /api/mixes/{id}
PATCH  /api/mixes/{id}
POST   /api/mixes/{id}/ingredients
PATCH  /api/mixes/{id}/ingredients/{ingredient_id}
DELETE /api/mixes/{id}/ingredients/{ingredient_id}
GET    /api/mixes/{id}/cost-breakdown
```

### Products

```
GET    /api/products
POST   /api/products
GET    /api/products/{id}
PATCH  /api/products/{id}
GET    /api/products/{id}/cost-breakdown
GET    /api/products/{id}/price-output
```

### Scenarios

```
GET    /api/scenarios
POST   /api/scenarios
GET    /api/scenarios/{id}
POST   /api/scenarios/{id}/run
GET    /api/scenarios/{id}/results
POST   /api/scenarios/{id}/approve
POST   /api/scenarios/{id}/reject
```

### Power BI

```
GET /api/powerbi/raw-material-costs
GET /api/powerbi/mix-costs
GET /api/powerbi/product-costs
GET /api/powerbi/scenario-results
GET /api/powerbi/data-quality-issues
```

---

# Calculation engine design

Use explicit calculation functions instead of trying to replicate Excel formulas blindly.

Example services:

```
calculate_raw_material_cost()
calculate_mix_cost()
calculate_product_cost()
calculate_selling_price()
calculate_scenario()
```

Each function should return:

```
calculated value
source inputs
warnings
formula version
timestamp
```

This gives you an audit trail and makes Power BI more trustworthy.

---

# Data validation rules

The app should actively prevent spreadsheet-style silent errors.

## Raw materials

| Rule | Severity |
| --- | --- |
| Missing market value | Error |
| Kg per unit is zero | Error |
| Missing unit of measure | Warning |
| Waste % over threshold | Warning |
| Duplicate raw material name | Warning |

## Mixes

| Rule | Severity |
| --- | --- |
| Mix has no ingredients | Error |
| Total kg is zero | Error |
| Ingredient has no active price | Error |
| Recipe has unresolved note | Warning |
| Ingredient quantity unusually high | Warning |

## Products

| Rule | Severity |
| --- | --- |
| Product has no linked mix | Error |
| Missing unit of measure | Error |
| Missing bagging process | Warning |
| Missing margin rule | Error |
| Freight rule not found | Warning |
| Manual override exists | Warning |

---

# Import and migration plan

## Phase 1: Workbook audit and import

Build an Excel import script that extracts:

```
StraightGrain table
AllMix table
ProductCost table
Price Review table
Stock Take data
Sales R12M data
Workbook comments
```

Do not import formulas as the production logic. Import formulas only as a reference for testing.

---

## Phase 2: Formula parity testing

Before replacing the spreadsheet, create test cases from known workbook rows.

For example:

```
Raw material:
Acid Buf cost per kg

Mix:
Pigeon Mix cost per kg

Product:
Specialty Pigeon Breeder 20kg finished delivered cost
Distributor price
Wholesale price
```

The backend should calculate the same or near-same results as the workbook before the client uses it.

---

## Phase 3: Build operational app

Start with these modules:

```
1. Raw Materials
2. Mix Master
3. Product Cost
4. Scenario calculator
5. Power BI endpoint
```

Leave Xero integration, advanced approvals, and full stock/sales analytics until after the costing logic is stable.

---

# Recommended delivery phases

## Phase 0 — Discovery and formula mapping

Outcome:

```
Confirmed calculation rules
Confirmed edge cases
Confirmed client workflow
Confirmed Power BI output requirements
```

Tasks:

```
Map every key formula
Identify hardcoded assumptions
Identify manual overrides
Confirm Xero source fields
Confirm which spreadsheet sheets are still required
```

---

## Phase 1 — Data model and import prototype

Outcome:

```
Workbook imported into database
Raw materials, mixes, and products visible in the app
```

Build:

```
PostgreSQL schema
Excel import script
Raw Materials page
Mix Master read-only page
Product Cost read-only page
```

---

## Phase 2 — Calculation engine

Outcome:

```
Backend calculates product unit costs without relying on Excel
```

Build:

```
Raw material calculation
Mix cost calculation
Product cost calculation
Margin calculation
Freight/packaging/process rule engine
Formula parity tests against spreadsheet
```

---

## Phase 3 — Client data entry

Outcome:

```
Client can maintain costing inputs safely
```

Build:

```
Editable raw materials
Editable mix recipes
Editable product settings
Validation warnings
Audit trail
Role-based permissions
```

---

## Phase 4 — Scenarios and price review

Outcome:

```
Client and consultancy can simulate price changes and approve outputs
```

Build:

```
Scenario creation
Scenario comparison
Price review workflow
Manual override tracking
Approval status
```

---

## Phase 5 — Power BI integration

Outcome:

```
Power BI consumes governed costing outputs
```

Build:

```
Power BI API endpoints
Database views
Refresh-friendly output tables
Data quality issue feed
Scenario comparison feed
```

---

## Phase 6 — Xero integration

Outcome:

```
Xero item data and possibly raw cost data are synchronised
```

Build later:

```
Xero item mapping
Xero item import
Sync status
Conflict detection
Optional write-back, only if approved
```

---

# Minimum viable product

For the first usable version, build only this:

```
Raw Materials
Mix Master
Product Cost
Scenario Calculator
Power BI Output
```

Avoid building a full ERP-style system too early.

The MVP should answer:

```
What does this product cost now?
Why does it cost that?
What changed?
What price should we charge?
What would happen if raw material prices changed?
Can Power BI report on it?
```

---

# Key technical recommendations

## Frontend

Use:

```
SvelteKit
TypeScript
TanStack Table or similar grid library
Form validation with Zod
Clean scenario comparison pages
Role-based navigation
```

## Backend

Use:

```
FastAPI
SQLAlchemy
Alembic migrations
PostgreSQL
Pydantic schemas
pytest for formula parity tests
```

## Power BI

Best option:

```
Power BI connects to PostgreSQL reporting views
```

Acceptable option:

```
Power BI connects to FastAPI JSON endpoints
```

The database view option is usually cleaner, faster, and easier to refresh.

---

# Main risks

| Risk | Mitigation |
| --- | --- |
| Spreadsheet formulas contain hidden business rules | Complete formula mapping before build |
| Client expects spreadsheet flexibility | Add scenario mode and manual override tracking |
| Raw material names do not match across sheets | Use internal IDs, not names, after import |
| Xero data is inconsistent | Create mapping and review workflow |
| Power BI consumes unstable draft data | Publish only approved scenario outputs |
| Manual overrides break trust | Make overrides visible and auditable |

---

# Recommended build principle

Do not build a “spreadsheet on the web”.

Build a controlled costing platform with:

```markdown
structured data
versioned assumptions
transparent calculations
scenario comparison
approval workflow
Power BI-ready outputs
```

That gives the client safer data entry, gives the consultancy control and visibility, and gives Power BI a clean source instead of fragile workbook logic.

---

# Frontend layout debugging notes

## Full-height layouts inside padded shells

When a child layout uses negative margins to cancel a parent container's padding, `height: 100%` is often not enough to visually fill the container.

Example pattern:

```css
.parent {
  --content-padding: 1.34rem;
  padding: var(--content-padding);
}

.child {
  margin: calc(var(--content-padding) * -1);
  height: 100%;
}
```

This can leave a visible gap at the bottom because the child is still only `100%` tall while being visually expanded outward by the negative margins.

Preferred fix:

```css
.child {
  margin: calc(var(--content-padding) * -1);
  height: calc(100% + (var(--content-padding) * 2));
  min-height: calc(100% + (var(--content-padding) * 2));
}
```

Worker reasoning rule:

- If a panel "almost" fills the viewport but leaves a strip equal to parent padding, inspect negative margins and the nearest padded scroll container before changing inner child heights.
- In this app, `AppSecondaryRailLayout.svelte` sits inside `ClientShell.svelte`'s padded `.content` container, so full-height fixes should account for `--content-padding`.
