🧬 Masscience

Build Muscle. Control the Rate. Minimize Unnecessary Fat Gain.

A privacy-first, client-side lean bulk & mini-cut companion built around bodyweight trends instead of obsessive calorie tracking.

🚀 Try Masscience · 📖 Documentation · 🧮 Algorithms · 🤝 Contributing

🎯 What is Masscience?

Masscience is a data-driven bodyweight and nutrition management application designed for people who want to gain muscle while keeping unnecessary fat gain under control.

Traditional bulking often creates two extremes:

"I'll just eat everything and hope I gain muscle." 

or:

"I need to weigh every ingredient of every meal." 

Masscience takes a different approach.

The core idea

You don't necessarily need to know exactly how many calories you ate. You need to know how your body is responding.

Masscience observes the user's bodyweight trajectory and uses that information to estimate whether the current calorie target is producing the desired rate of gain.

🧠 How It Works

The user does not need to understand the mathematics behind this system.

Masscience handles the calculations.

⚡ Core Features

🏋️ Lean Bulk / Mini-Cut Cycles

Masscience uses a default cycle of:

10 weeks — Lean Bulk        ↓ 3 weeks — Mini-Cut        ↓ Repeat 

Initial calorie targets:

Lean Bulk
Mini-Cut

The system can adapt the calorie target based on observed weight trajectory.

⚖️ Smart Weigh-In Frequency

One of the main goals of Masscience is to reduce the annoyance of constant weighing.

Instead of requiring daily measurements indefinitely, the application progressively reduces the frequency when enough evidence exists.

If the trend becomes unreliable, Masscience can increase measurement frequency again.

Missing days

When a measurement is missing, Masscience can estimate the expected weight using the current trend.

Estimated values are explicitly marked as:

ESTIMATED 

They are never presented as actual measurements.

📈 Intelligent Weight Tracking

Daily bodyweight is noisy.

A person can gain or lose more than a kilogram without meaningfully changing their body composition.

Masscience therefore analyzes the trend, rather than reacting to individual measurements.

The trend engine accounts for:

• day-to-day noise
• outliers
• measurement frequency
• rolling observation windows
• regression
• trend confidence
• rate of change

Primary metrics:

Current weight Trend weight Rate of gain % bodyweight/week Trend confidence 

🎯 Adaptive Gain Targets

Masscience does not simply tell everyone:

Gain 0.2 kg/week. 

Instead, its primary target is expressed relative to bodyweight:

% bodyweight / week 

This makes the target scale between users.

The target can be influenced by:

• bodyweight
• training age
• current BF estimate
• training frequency

The objective is a conservative bulk with enough progression to support muscle gain while avoiding unnecessarily aggressive weight gain.

🧠 Adaptive TDEE

Masscience starts with an estimated TDEE:

BMR × Activity Factor 

As the user accumulates data, the application can infer an effective TDEE from:

Observed weight change + Calorie target + Time 

The system intentionally distinguishes between:

Calories prescribed 

and:

Calories actually consumed 

If the user does not log their food intake, Masscience cannot know their exact intake.

Therefore TDEE is presented as an estimate with uncertainty.

🧬 Body Composition

Masscience estimates:

• Body-fat %
• Fat mass
• Lean mass
• FFMI

Possible inputs include:

• initial user estimate
• waist circumference
• neck circumference
• height
• bodyweight

The application can use the U.S. Navy body-fat equation when appropriate.

Important distinction

Lean Mass ≠ Muscle Mass 

Lean mass contains water and other non-fat tissues in addition to skeletal muscle.

Masscience does not pretend that an estimated increase in lean mass is an exact measurement of muscle growth.

🔮 Future Projection

Masscience can simulate possible outcomes for the end of a cycle.

Instead of producing:

You WILL weigh 68.4 kg. 

it produces an estimated distribution:

Expected weight        16%       50%       84%        │         │         │        ▼         ▼         ▼      67.2      68.0      68.9 kg 

The projection engine uses Monte Carlo simulation to model uncertainty in future trajectories.

Possible outputs include:

• projected weight
• projected BF
• projected lean mass
• projected fat mass
• projected FFMI
• trajectory risk

🎛️ Adaptive Calorie Controller

Masscience uses a conservative feedback-control system.

             TARGET RATE                   │                   ▼           ┌───────────────┐           │ Compare with  │           │ actual trend  │           └───────┬───────┘                   │                   ▼               RATE ERROR                   │                   ▼              CONFIDENCE                   │                   ▼           ┌───────────────┐           │ Controller    │           │ + Deadband    │           │ + Cooldown    │           └───────┬───────┘                   │                   ▼           CALORIE ADJUSTMENT 

The controller deliberately avoids making large changes based on a single noisy measurement.

It uses:

• rate error
• trajectory error
• confidence
• deadband
• minimum evidence
• discrete adjustment steps
• cooldown periods

📊 Confidence Instead of False Precision

Masscience does not use one giant "accuracy score."

Different parts of the system have different uncertainty.

Therefore it maintains separate confidence concepts:

Trend Confidence
How reliable the observed weight trend is
TDEE Confidence
How much evidence supports the TDEE estimate
BF Confidence
Confidence in body-fat estimation
Projection Confidence
Confidence in future trajectory

This allows the application to communicate uncertainty honestly.

🔬 Algorithm

Current algorithm version:

2.1.0 

Masscience's mathematical engine is modular.

js/ ├── calculations.js ├── trend.js ├── composition.js ├── control.js ├── adaptive.js ├── projection.js ├── confidence.js ├── cycle.js └── storage.js 

Trend

Current approach:

Rolling OLS + Outlier downweighting + Adaptive observation window 

Composition

Current approach:

User BF estimate + Navy method + BF inertia + Uncertainty propagation 

Control

Current approach:

Weight trajectory + Rate error + Trajectory error + Confidence + Deadband + Cooldown 

Projection

Current approach:

Monte Carlo + Truncated-normal rate distribution + Uncertainty propagation 

🧪 Algorithm Development

Masscience treats its mathematical model as a first-class part of the project.

Every major algorithm should be:

• documented
• testable
• benchmarkable
• replaceable
• versioned

Algorithm changes are recorded in:

ALGORITHM_CHANGELOG.md 

Complete mathematical documentation:

ARCHITECTURE.md 

Build architecture:

BUILD_ARCHITECTURE.md 

🖥️ Platforms

🌐 Web
HTML/CSS/JS
Web App
🪟 Windows
Electron
🐧 Linux
Electron
🤖 Android
Capacitor

The same frontend is reused across all platforms.

                  HTML                    │              CSS + JavaScript                    │        ┌───────────┼───────────┐        │           │           │       Web       Electron    Capacitor        │           │           │        ▼       ┌───┴───┐       ▼    Browser     Win   Linux    Android 

🚀 Live Demo

🌐 Try Masscience

Open the Web App

No account required.

No backend required.

No installation required.

📦 Installation

Web

Simply open the deployed GitHub Pages application.

Or run locally:

git clone https://github.com/wesleyyan-sb/masscience.git cd masscience npm ci npm run dev

Windows / Linux / Android

Masscience includes an automated build system.

On Windows:

build.bat

One command can build:

Windows installer Linux AppImage Android APK Web build 

Individual targets can also be built:

build.bat windows build.bat linux build.bat android build.bat web

More information:

BUILD.md 

⚙️ Automated Builds

Masscience is designed around reproducible builds.

Developer     │     ▼ build.bat     │     ├───────────────┐     ▼               ▼ Web Build       Electron                     │               ┌─────┴─────┐               ▼           ▼            Windows      Linux               │           │              .exe     .AppImage                      Capacitor     │     ▼  Android     │    .apk 

GitHub Actions can also generate platform artifacts automatically.

🔐 Privacy First

Masscience is designed to be client-side and privacy-first.

Your data can remain entirely on your device.

There is no required:

• account
• backend
• cloud database
• telemetry server
• external AI
• nutrition API
• subscription

The application can work offline.

Your:

Weight BF estimates Measurements Calories Cycle history Projections 

do not need to leave your device.

📴 Offline-First

Core functionality is designed to work without an internet connection.

Offline functionality includes:

• weight tracking
• trend analysis
• BF estimation
• TDEE estimation
• calorie recommendations
• projections
• Monte Carlo simulations
• charts
• local persistence
• cycle management

Internet access is primarily useful for things such as downloading the application or accessing the web deployment.

🧪 Testing

Run the regression suite:

node js/tests/run-tests.js

Trend benchmark:

node js/tests/benchmark-trend.js

Monte Carlo benchmark:

node js/tests/benchmark-mc.js

The test suite covers areas such as:

• trend calculations
• outlier detection
• missing measurements
• BF inertia
• controller behavior
• Monte Carlo convergence
• cycle transitions
• projection behavior

🛣️ Roadmap

Core

• Lean bulk cycle
• Mini-cut cycle
• Weight tracking
• Trend analysis
• Adaptive calorie control
• BF estimation
• FFMI estimation
• Cycle projections
• Monte Carlo projections
• Confidence system
• Smart weigh-in frequency

Platforms

weigh every ingredient         + track every meal         + panic over daily weight fluctuations 

Train   ↓ Eat   ↓ Measure   ↓ Observe the trend   ↓ Adjust   ↓ Repeat