beaverhabits - Moses Yebei

The Problem

Most habit trackers force a "goals" model—streaks to maintain, targets to hit—which adds pressure and guilt. Beaver Habit Tracker strips that out: you just mark days done or not, and the app shows you the pattern. It's a self-hosted alternative to SaaS trackers, giving you full control over your data and no subscription.

What This Does

This is a Flask-based web app (Python, 71 files) that renders a server-side UI with JavaScript enhancements. The core loop is simple: you define habits, mark days complete, and the app renders calendars, streaks, and stats. Storage is pluggable—SQLite via SQLAlchemy (beaverhabits/app/db.py) or JSON files (beaverhabits/storage/dict.py).

The frontend is generated in Python (beaverhabits/frontend/components.py, 94 functions) rather than a JS framework. There's also a demo mode, user auth with API tokens, and a paid tier via Paddle (beaverhabits/plan/paddle.py). The statics/ folder holds PWA assets and vendor JS.

How It Is Wired

Execution starts in beaverhabits/main.py at the lifespan function, which reaches 17 functions. From there, the app initializes the database and starts a scheduler (beaverhabits/scheduler.py) that runs a daily backup task. The backup path is short: lifespan -> daily_backup_task -> backup_all_users -> get_user_habit_list, which hits the database via session.execute. So a single run touches the DB within 4 hops.

The request path is framework-driven (Flask routes in beaverhabits/routes/routes.py), which the static call graph can't see. But once a handler runs, everything funnels through beaverhabits/storage/storage.py (54 functions, 24 modules depend on it) and beaverhabits/app/crud.py (18 functions, 15 callers). The most-connected module is beaverhabits/configs.py—26 modules import it, making it a high-blast-radius hub. The beaverhabits/frontend/layout.py module sits in a circular import cycle with menu.py, which will complicate any refactor of the navigation.

How To Use It

Setup uses uv:

uv venv && uv sync
./start.sh dev

For Docker:

docker run -d --name beaverhabits \
  -u $(id -u):$(id -g) \
  -e HABITS_STORAGE=USER_DISK \
  -v ./beaver/:/app/.user/ \
  -p 8080:8080 \
  daya0576/beaverhabits:latest

Configuration is via environment variables: HABITS_STORAGE (DATABASE or USER_DISK), TRUSTED_LOCAL_EMAIL to skip auth, INDEX_HABIT_DATE_COLUMNS for layout. The container runs as nobody for security.

Real-World Use

A home server running the Docker container, with habits stored as a local JSON file. The USER_DISK storage mode means no database to manage—just a mounted volume. A user opens the PWA on their phone, marks "read" for the day, and the data persists to the mounted folder. Backups are automatic via the scheduler. The demo mode (beaverhabits.com/demo) shows the full UI without setup.

Code Health & Issues

Static analysis found 31 issues (6 high, 25 medium). Key findings:

High - Circular imports in beaverhabits/frontend/layout.py and menu.py—mutually reachable modules make changes risky.
High - Deep nesting (depth 6) in layout.py, storage/dict.py, and components.py—control flow is hard to follow.
High - Hub modules: configs.py has 26 dependents, storage.py has 24—changes ripple widely.
Medium - Broad exception handling in components.py, auth.py, menu.py—errors get swallowed.
Medium - Unclosed file handles in layout.py, javascript.py, export_page.py.

SDLC observations: CI exists (GitHub Actions), but workflows don't pin actions to commit SHAs (a security risk), lack least-privilege permissions, and have no dependency vulnerability scan. The Docker base image python:3.14-slim is unpinned by digest. No lockfile for Python deps means non-reproducible builds.

The Bottom Line

This is a functional, self-hosted habit tracker with a clean UI and sensible storage abstraction. The codebase is mature enough for personal use, but the circular imports and hub modules will make significant refactoring painful. Use it if you want a no-frills tracker you control; plan for a security pass on CI before exposing it publicly.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

113 files

Python71
YAML6
JavaScript5
Markdown4
JSON3
Shell2

FlaskExpressDocker

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["beaverhabits<br/>62 modules"] g1["tests<br/>8 modules"] g2["statics<br/>3 modules"] g1 -->|22| g0

Module dependencies

The 10 most depended-upon modules of 74, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_beaverhabits_configs["configs"] n1_beaverhabits_storage_storage["storage"] n2_beaverhabits_app_db["db"] n3_beaverhabits_logger["logger"] n4_beaverhabits___init__["__init__"] n5_beaverhabits_frontend_layout["layout"] n6_erhabits_frontend_components["components"] n7_beaverhabits_utils["utils"] n8_averhabits_frontend___init__["__init__"] n9_beaverhabits_storage_dict["dict"] n2_beaverhabits_app_db --> n0_beaverhabits_configs n6_erhabits_frontend_components --> n4_beaverhabits___init__ n6_erhabits_frontend_components --> n0_beaverhabits_configs n6_erhabits_frontend_components --> n8_averhabits_frontend___init__ n6_erhabits_frontend_components --> n3_beaverhabits_logger n6_erhabits_frontend_components --> n9_beaverhabits_storage_dict n6_erhabits_frontend_components --> n1_beaverhabits_storage_storage n6_erhabits_frontend_components --> n7_beaverhabits_utils n5_beaverhabits_frontend_layout --> n4_beaverhabits___init__ n5_beaverhabits_frontend_layout --> n0_beaverhabits_configs n5_beaverhabits_frontend_layout --> n8_averhabits_frontend___init__ n5_beaverhabits_frontend_layout --> n6_erhabits_frontend_components n5_beaverhabits_frontend_layout --> n1_beaverhabits_storage_storage n3_beaverhabits_logger --> n0_beaverhabits_configs n9_beaverhabits_storage_dict --> n3_beaverhabits_logger n9_beaverhabits_storage_dict --> n1_beaverhabits_storage_storage n9_beaverhabits_storage_dict --> n7_beaverhabits_utils n1_beaverhabits_storage_storage --> n2_beaverhabits_app_db classDef cyc stroke:#ef4444,stroke-width:2px; class n5_beaverhabits_frontend_layout cyc;

Findings

LowDependencies declared without a lockfile - non-reproducible builds pyproject.toml

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high1

medium5

low1

Pin third-party GitHub Actions to a commit SHAhigh7 occurrences

.github/workflows

superfly/flyctl-actions/setup-flyctl@master, astral-sh/setup-uv@v4, docker/metadata-action@v5, docker/setup-qemu-action@v3

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Declare least-privilege permissions for GITHUB_TOKENmedium3 occurrences

.github/workflows/fly.yml

3 workflow(s) declare no permissions, 2 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

docker/Dockerfile

python:3.14-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/fly.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/copilot-setup-steps.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.