GoodNumbers 🩸

A smart weekly journal for type 1 diabetics.

GoodNumbers is an experimental, non-commercial, open-source project designed to help people with Type 1 Diabetes reflect on and improve their blood sugar management through a weekly practice of self-reflection.

---

🚀 What is GoodNumbers?

GoodNumbers is a weekly journal that combines traditional statistical analysis with modern AI to help you identify trends and patterns in your diabetes management.

• Statistical Analysis: Automatically identify "hotspots" and troublesome trends in your blood glucose data.
• AI-Powered Reflection: Leverage AI to reflect on strategies, celebrate wins, and find blind spots.
• Weekly Practice: A dedicated pause in your week to look back, learn, and improve for the next seven days.
• Motivation without Judgment: Designed to be a positive, motivating tool for a challenging daily job.

gn_ai_demo_small.mp4

Note: GoodNumbers is an experiment and is for educational use only. It is not a medical device and does not provide medical advice.

---

🛠️ Built With

• Frontend: React (Vite), TypeScript, Tailwind CSS, Refine (v5)
• Backend: Node.js, Express, Prisma, Auth.js (NextAuth for Express)
• Data: SQLite (Standardized on absolute pathing for both Dev and Production), Redis (for background jobs)
• AI: Gemini 3.1 Pro (via Google AI Studio) for deep clinical reasoning

---

🚀 Quick Start

Setting up GoodNumbers for local development is easy with our just command runner.

1. Clone and Setup:

   git clone https://github.com/ssuppe/goodnumbers.git
   cd goodnumbers
   just setup

2. Configure Environment: Edit the newly created .env file in the root and add your credentials:

   • AUTH_SECRET (A secure random string for signing cookies)
   • AUTH_URL (Base URL of your frontend, e.g., http://localhost:5173)
   • GEMINI_API_KEY (from Google AI Studio)

   Note on Registration: This project uses a restricted sign-up flow. You must add your email to backend/config/allowed_emails.txt before you can register an account.

3. Launch:

   just dev          # Starts Redis, Backend, Worker, and Frontend

   Alternatively, run the production-ready Docker stack:

   just docker-prod   # Access at http://localhost:8100

4. Access: Open http://localhost:5173 (local dev) or http://localhost:8100 (Docker preview) in your browser.

---

✨ Key Features

GoodNumbers provides a multi-layered analysis of your 7-day diabetes data:

📊 Statistical Analysis & Heuristics (Ground Truth)

The core of the report is built on robust statistical methods and deterministic logic:

• Ambulatory Glucose Profile (AGP): A standardized chart showing your blood sugar patterns and percentiles (5th, 25th, 50th, 75th, 95th) over a 24-hour period.
• Voyager Scorecards: Key performance metrics including Average Glucose, Stability (Rate of Change), and Time in Range (Standard and Tight).
• Overnight Glucose Control: A specialized analysis of the 11 PM to 7 AM window, evaluating stability against Normal, Tight, and Standard clinical ranges.
• Bolus Timing Heuristics: A deterministic engine that identifies:
  • Uncovered Meals: Meals detected without matching insulin.
  • Post-bolusing: Insulin given at or after the start of a meal.
  • Pre-bolusing: Insulin given significantly before a meal.
• Glycemic Hotspot Detection: Automatically identifies recurring "clusters" of highs or lows at specific times of day.

🧪 Testing

We take reliability seriously. Run the full suite with:

just test

---

🧬 Development & Testing

We follow a strict Test-Driven Development (TDD) workflow.

Quality Gates

Run these commands before pushing:

• Linting: npm run lint
• Tests: npm test (Runs all 350+ backend and frontend tests)
• Reset Environment: just redis-flush && just db-reset-dev

For more details on contributing, see CONTRIBUTING.md.

---

🤖 How This Project Was Created

GoodNumbers was created using a human-in-the-loop AI development process.

The majority of the code, tests, and documentation were generated by AI agents (using the Gemini API and related tooling). The project is steered and reviewed by a former software engineer who acted as the "Senior Tech Lead." While every line of code has been reviewed for intent and functionality, this remains an experimental project.

The author offers NO GUARANTEES of correctness, safety, or reliability.

This project is a demonstration of how AI can assist in building complex health-tech tools, but it must be used with extreme caution.

---

📅 TODO / Next Steps

• Data Export: Export your reflections as a PDF or Markdown file for sharing with healthcare teams.
• More Heuristics: Expand analysis to include exercise patterns and stress markers.
• Cloud Hosting: Streamline the one-click deployment for non-technical users.

---

⚖️ License

Distributed under the AGPL-3.0 License. See LICENSE for more information.

---

Medical Disclaimer: This software is not intended for medical use. Read the full DISCLAIMER.md before use.

---

GoodNumbers is dedicated to the idea that better data and regular reflection can lead to better outcomes.