Flask-based internal roll diameter calculator for Naue roll products. The app is a small authenticated Flask shell around a mostly client-side calculator UI.

This README is intended for developers maintaining the project, not for end users.

Runtime Stack

Python 3
Flask 2.3.3
Flask-HTTPAuth 4.8.0
Vanilla HTML, CSS, and JavaScript
JSON files for product data and forklift/load rules

Pinned Python dependencies are defined in requirements.txt.

Local Setup

Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Start with the hardcoded settings in app.py:

python app.py

By default this attempts to bind to:

http://localhost:5000

If port 5000 is already occupied, start through Flask's CLI without changing files:

flask --app app run --host 127.0.0.1 --port 5001

The app uses HTTP Basic Auth. Current credentials are defined in BETA_USERS in app.py.

Project Layout

.
├── app.py
├── requirements.txt
├── README.md
├── access_log.json
├── config.json
├── article-data_.json
├── fix_article_data.py
├── service-worker.js
├── templates/
│   └── roll_calculator.html
├── static/
│   ├── article-data.json
│   ├── config.json
│   ├── service-worker.js
│   ├── stddev_calculator.js
│   ├── direct_calc_handler.js
│   ├── rollcalc_v14.js
│   ├── rollcalc_improvements.js
│   ├── rollcalc-improvements.js
│   ├── rollcalc_stddev_ranges.js
│   └── rollcalc_stddev_integration.js
└── docs/
    ├── DEPLOYMENT_GUIDE.md
    ├── QOL_UPDATE_SUMMARY.md
    ├── STDDEV_IMPLEMENTATION_CHECKLIST.md
    └── STDDEV_RANGES_DOCS.md

Backend

app.py owns the Flask application and authentication.

Implemented routes:

Route	Methods	Auth	Purpose
`/`	`GET`	Basic Auth	Renders `templates/roll_calculator.html`.
`/static/<path:filename>`	`GET`	Basic Auth	Intended protected static-file serving from `static/`.
`/api/health`	`GET`	Basic Auth	Returns app health and version.
`/api/user`	`GET`	Basic Auth	Returns current authenticated user info.

Authentication is implemented with Flask-HTTPAuth. The current code checks BETA_USERS and performs direct plaintext string comparison.

Access logging is handled by log_access(), which reads access_log.json, appends a record, and writes the whole file back.

Frontend Entry Point

The active UI is templates/roll_calculator.html.

The template contains:

Page layout and all main CSS.
A disclaimer modal shown after Basic Auth login and before calculator use.
Global state:
- window.ARTICLE_DATA
- window.APP_CONFIG
Product/article data loading from /static/article-data.json.
Direct roll calculations.
Extrapolation calculations.
Forklift/weight warnings.
Load optimizer UI and calculations.

Most of the currently active JavaScript is inline in this template. Several files under static/ appear to be older, alternative, or integration-oriented modules and should be checked before assuming they are active.

Main Functional Areas

Disclaimer Gate

The calculator page displays a modal disclaimer before use. The modal:

Shows German and English disclaimer text.
Requires a checkbox confirmation.
Keeps the confirmation button disabled until checked.
Hides the overlay after confirmation.

This is implemented in templates/roll_calculator.html and is client-side only.

Article Data Loading

templates/roll_calculator.html fetches:

/static/article-data.json

The loaded array is assigned to window.ARTICLE_DATA and used to populate article datalists for direct calculation and extrapolation.

Known article fields used by the UI include:

nr
name
thickness
thickness_stddev
area_weight
area_weight_stddev
core_type

The active static/article-data.json currently contains product records with additional min/max/count statistics.

Direct Calculation

The direct calculation tab supports multiple modes via mode buttons:

Roll diameter from core diameter, material thickness, and product length.
Product length from core diameter, material thickness, and roll diameter.
Product length for a target diameter.

The nominal roll diameter formula used in the template is:

D = sqrt(d^2 + (4 * L * 1000 * t) / pi)

Where:

D is roll diameter in mm.
d is core diameter in mm.
L is product length in m.
t is material thickness in mm.

If a tolerance/stddev value is present, the UI also displays a -2σ and +2σ diameter range.

Roll weight is calculated when roll width, area weight, and length are present:

weight_kg = area_weight_g_m2 * length_m * width_m / 1000

Extrapolation

The extrapolation tab estimates a new roll diameter from a known roll diameter/length pair and a new target length:

D1 = sqrt(d^2 + (L1 / L0) * (D0^2 - d^2))

Where:

d is core diameter.
D0 is measured/current diameter.
L0 is measured/current length.
L1 is target length.
D1 is the calculated new diameter.

Forklift Check

checkForklift() in templates/roll_calculator.html evaluates heavy-roll warnings using window.APP_CONFIG.forklift_rules.

The current inline config targets the bentofix category and includes:

Warning threshold: 1700 kg
Hard limit: 2750 kg
Minimum core outer diameter requirement: 170 mm

There is also a richer static/config.json with localized messages and more detailed requirements.

Load Optimizer

The Load Optimizer is implemented by inline classes in templates/roll_calculator.html:

LoadOptimizer
LoadOptimizerUI

It uses calculated roll data from the Direct Calculation tab and estimates loading capacity for transport presets or custom dimensions.

Preset transport units include:

20ft Container
40ft Container
40ft High Cube
LKW Sattelzug
LKW Tandem

The optimizer calculates limiting scenarios by:

Weight
Volume
Geometry

It also renders a side-view SVG visualization of the loading arrangement.

Standard Deviation Modules

There are standalone/static modules for standard deviation logic:

static/stddev_calculator.js
static/rollcalc_stddev_ranges.js
static/rollcalc_stddev_integration.js

These provide or describe range calculations for material thickness, area weight, roll diameter, and roll weight. Check actual script inclusion before treating them as active in production, because the current template already contains inline stddev/tolerance behavior.

Admin UI

RollCalc no longer contains an admin UI or admin API. Login/access logging remains in the backend, but logs are not exposed through a RollCalc admin screen.

Administration and maintenance of article-data.json is planned for a separate application. RollCalc should continue to consume static/article-data.json read-only.

Static Assets and Data Files

`static/article-data.json`

Primary product/article dataset used by the active calculator UI.

`static/config.json`

JSON configuration for forklift/heavy-roll rules. The active template also contains an inline window.APP_CONFIG, so developers should verify which config source is authoritative before changing rule behavior.

`access_log.json`

JSON audit log written by app.py.

Important implementation detail: each logged access reads and rewrites the entire JSON file. This is simple but not concurrency-safe and can become inefficient as the file grows.

`fix_article_data.py`

Utility script that updates relative frontend fetch/register paths to Flask-style /static/... paths and checks that key static files exist.

Development Notes

The codebase is currently closer to a single-page static calculator wrapped by Flask than to a conventional Flask MVC app.
The active calculator logic is concentrated in templates/roll_calculator.html.
There are duplicated or legacy-looking files with similar names. Before editing JavaScript under static/, confirm it is actually referenced by the active template.
The documentation under docs/ contains deployment and feature notes, but some filenames and route assumptions may not match the current app exactly.
The Flask dev server is used for local development only. Production should use a WSGI server.

Known Risks and Maintenance Items

Credentials are hardcoded in app.py and should be moved to environment variables or a secrets manager.
Passwords are stored in plaintext and compared directly.
access_log.json is not safe for concurrent writes.
access_log.json grows without rotation or retention limits.
The custom /static/<path:filename> route is intended to protect static files, but Flask also creates a default static route unless disabled. Verify effective route behavior before relying on static-file protection.
RollCalc no longer includes an admin UI/API; article data administration belongs in a separate application.
There is no visible automated test suite.
The main template is large and mixes layout, styling, data loading, calculations, and UI behavior.
The disclaimer confirmation is client-side only and is not persisted or audited server-side.

README.md Unescape Escape

RollCalcPython