Thanks to visit codestin.com
Credit goes to github.com

Skip to content

shchukins/human-engine

Repository files navigation

Human Engine

Русская версия

Train around your life, not around a plan.


Why Human Engine

Most training platforms assume you live for training. You adjust your sleep, your work, your weekends — to fit the plan. Human Engine flips this.

It reads your recovery, looks at your day, and tells you what kind of training makes sense right now — not what the template says.


Your ecosystem, your data

You don't need Garmin to get Garmin-quality load analysis. Human Engine works with whatever you already use — Wahoo, Zwift, Rouvy, Apple Watch, any trainer that exports to Strava. No ecosystem lock-in. No hardware requirements.

Strava and Apple Health are the connectors. Everything else is yours.


What it does

Morning readiness briefing — the backend already produces a daily readiness result with explanation, a deterministic recommendation zone, and Telegram/iOS-friendly briefing text.

Deterministic training guidance — the current product maps readiness into explicit training guidance like recovery, endurance, moderate, or high_intensity. Broader day-planning logic such as calendar-aware timing or duration selection remains planned.

Explainable outputs — every recommendation shows its reasoning. HRV down, sleep short, high fatigue — you see exactly why. No black box.


How it works

Strava + Apple Health
        ↓
load model + recovery model
        ↓
readiness score + explanation
        ↓
training recommendation
        ↓
morning briefing

The core is deterministic and reproducible. AI is an auxiliary layer, not the product — every output can be traced back to a formula and a data point.


Principles

  • your data stays yours — self-hosted, no third-party cloud
  • deterministic core: same inputs always produce the same outputs
  • explainability over accuracy theatre — know why, not just what
  • ecosystem-agnostic: works with any hardware that talks to Strava or Apple Health

Status

Active prototype. Core pipeline is working end-to-end: Strava and HealthKit data flow into daily load, recovery, readiness, and deterministic recommendation outputs. Daily readiness is available through the API and Telegram delivery. Broader planning and calibration work remain in active development.

Operational Surfaces

  • shchukin.de is the main web domain for user/admin web surfaces.
  • shchukin.de/dashboard serves the internal dashboard as a FastAPI server-side rendered HTML page.
  • api.shchukin.de remains the technical API domain for FastAPI endpoints, Strava OAuth callback, Telegram webhook, HealthKit sync, /healthz, and API docs when enabled.

Current dashboard implementation:

  • FastAPI SSR route: /dashboard
  • Jinja2 templates with minimal CSS
  • no SPA and no frontend build step
  • current sections: System, Connection, Ingest Jobs, and Strava Activities
  • the dashboard reads local backend/database state only; it does not call Strava, refresh tokens, modify database rows, or expose access/refresh tokens or secrets

Security note:

  • the internal dashboard is protected at the edge with Caddy Basic Auth
  • Google OAuth restricted to a single allowed user email remains the preferred future authorization model

Operational monitoring note:

  • the FastAPI SSR dashboard is the primary operational monitoring surface for the current VPS production backend
  • the old home-server Telegram watchdog / cron-style monitoring is legacy and should not be treated as the main production monitoring channel

Documentation

Support

Human Engine is an independent open-source project. Infrastructure and development are self-funded — if you'd like to help, Telegram Stars are welcome.

About

Human Engine is an experimental training analytics platform built around Strava ingestion, FastAPI, PostgreSQL, and self-hosted infrastructure.

Topics

Resources

License

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

1 watching

Forks

Releases

No releases published

Packages

 
 
 

Contributors