scot/diligence
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

v2.0: dual deployment — pip install (SQLite) + Docker (PostgreSQL)

Browse source 
Architecture:
- Moved backend/app/ to diligence/ Python package
- Dialect-agnostic models (Uuid + JSON, no PostgreSQL imports)
- Auto-detect database: empty DATABASE_URL → SQLite at ~/.diligence/data.db
- Cross-dialect migrations (inspector-based, no raw PostgreSQL DDL)
- FastAPI serves pre-built React frontend for pip path
- CLI entry point: diligence [--port] [--no-browser] [--data-dir]
- pyproject.toml with optional deps: [postgres], [mcp], [dev]
- Docker path unchanged: docker compose up -d

pip install path: pip install . && diligence
Docker path: ./setup.sh && docker compose up -d
This commit is contained in:
Claude 2026-07-01 03:30:12 +00:00
parent 0ce1463de8
commit a6e6e2f54f
77 changed files with 1537 additions and 1007 deletions
Download patch file Download diff file Expand all files Collapse all files

376
README.md
View file

@ -1,237 +1,211 @@
# Diligence — Self-Hosted Fitness Rewards with AI Agent Support
# Diligence
Points-based fitness accountability app. Log workouts and food, earn points, unlock rewards. Connect any AI agent via MCP for logging, coaching, and meal planning. Self-hosted, open source, zero cloud dependencies.
Self-hosted fitness rewards platform with AI agent integration. Points-based behavioral economy: earn points through workouts and food logging, spend them on rewards you choose. Science-based onboarding. 14-tool MCP connector for AI agents. Your data stays on your machine.
Built by [DiligenceWorks](https://diligenceworks.online).
## Quick Start
### Prerequisites
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) — that's it. No Python, Node.js, or database install needed.
- Docker Desktop runs natively on **Windows 10/11**, **macOS**, and **Linux**.
**By [DiligenceWorks Pte. Ltd.](https://diligenceworks.online) — MIT License**
---
### Windows 11 Setup
## Which install is right for you?
**1. Install Docker Desktop**
| | **pip install** | **Docker** |
|---|---|---|
| **Who it's for** | You want a fitness app on your laptop. No servers, no DevOps, no fuss. | You're self-hosting for a household, a team, or you want PostgreSQL and a production-grade setup. |
| **What you need** | Python 3.11+ | Docker and Docker Compose |
| **Database** | SQLite (zero config, file on disk) | PostgreSQL 16 (runs in a container) |
| **Runs as** | Single process on localhost | 4 containers behind nginx |
| **Setup time** | 2 minutes | 5 minutes |
| **Best for** | Personal use on a laptop or desktop | Always-on server, multiple users, backups |
Download from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/).
---
During installation, the installer presents a checkbox: **"Use WSL 2 instead of Hyper-V (recommended)"**. This is checked by default.
## Install — Personal Laptop (pip)
- **WSL 2 backend (default):** Works on all Windows editions including Home. Lower resource usage, better performance. Requires WSL 2 to be installed first — open PowerShell as Administrator and run `wsl --install`, then reboot.
- **Hyper-V backend:** If WSL 2 causes issues (black screen on reboot, kernel errors, or containers won't start), uncheck the WSL 2 box during installation to use Hyper-V instead. Requires Windows Pro, Enterprise, or Education.
**Prerequisites:** Python 3.11 or newer.
**Important:** Hardware virtualization must be enabled in your BIOS/UEFI settings (Intel VT-x or AMD-V). This is the most common cause of "Docker won't start" issues. Check your laptop/PC manufacturer's documentation for how to access BIOS settings (usually F2, F12, or Del during boot).
```bash
# Clone and install
git clone https://github.com/DiligenceWorks/Diligence.git
cd Diligence
pip install .
**2. Clone and run**
Open PowerShell:
```powershell
git clone https://github.com/diligenceworks/diligence
cd diligence
powershell -ExecutionPolicy Bypass -File setup.ps1
docker compose up -d
# Run
diligence
```
Or without the script:
```powershell
git clone https://github.com/diligenceworks/diligence
cd diligence
copy .env.example .env
# Edit .env and set SECRET_KEY to any random string
docker compose up -d
That's it. The app opens in your browser at `http://localhost:8000`. Your data lives in `~/.diligence/`.
On first run, Diligence generates a secret key and stores your config in `~/.diligence/.env`. The SQLite database is created automatically at `~/.diligence/data.db`.
### Options
```bash
diligence --port 9000 # Different port
diligence --no-browser # Don't auto-open browser
diligence --data-dir /my/path # Custom data directory
python -m diligence # Alternative way to run
```
### Building the frontend from source
The pip package includes a pre-built frontend. If you want to modify the UI:
```bash
cd frontend
npm install
npm run build
cp -r dist/ ../diligence/frontend/
```
---
### macOS Setup
## Install — Server (Docker)
**1. Install Docker Desktop**
**Prerequisites:** Docker and Docker Compose.
Download from [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/). Make sure you pick the right installer for your chip:
- **Apple Silicon** (M1, M2, M3, M4) — download the Apple Silicon .dmg
- **Intel** — download the Intel .dmg
To check: Apple menu → About This Mac. Look for "Chip" (Apple Silicon) or "Processor" (Intel).
Drag Docker.app to Applications and launch it. Requires macOS 13 Ventura or later.
Alternatively, install via Homebrew: `brew install --cask docker`
**2. Clone and run**
Open Terminal:
```bash
git clone https://github.com/diligenceworks/diligence
cd diligence
./setup.sh
docker compose up -d
git clone https://github.com/DiligenceWorks/Diligence.git
cd Diligence
./setup.sh # generates .env with secrets
docker compose up -d # starts 4 containers
```
Open `http://localhost` (or your server's IP). Register your account — the first user gets admin.
### What's running
| Container | Role | Port |
|-----------|------|------|
| frontend | React app + nginx reverse proxy | 80 |
| backend | FastAPI application server | 8000 (internal) |
| mcp-connector | MCP SSE server for AI agents | 3001 |
| fitness-db | PostgreSQL 16 | 5432 (internal) |
### Environment variables
Copy `.env.example` to `.env` (or let `setup.sh` do it). Key variables:
| Variable | Docker default | Description |
|----------|---------------|-------------|
| `SECRET_KEY` | (generated) | JWT signing key |
| `API_TOKEN` | (generated) | MCP connector auth token |
| `DATABASE_URL` | `postgresql+asyncpg://...` | Database connection |
| `BASE_URL` | `http://localhost` | Public URL for OAuth callbacks |
---
## AI Agent Integration (MCP)
Diligence exposes 14 tools via the [Model Context Protocol](https://modelcontextprotocol.io). Any MCP-compatible AI agent (Claude, custom agents) can log workouts, track food, manage meal plans, and check progress.
### Connect your agent
**pip install path:**
```
URL: http://localhost:8000/mcp
Token: (shown on first run, or check ~/.diligence/.env)
```
**Docker path:**
```
URL: http://localhost:3001/sse
Token: (in your .env file, API_TOKEN)
```
### Available tools
| Tool | What it does |
|------|-------------|
| `get_context()` | Full profile, motivation type, programs, rules, rewards |
| `get_today()` | Daily points, gate status, activities |
| `get_week()` | Weekly summary and target progress |
| `log_activity(...)` | Log a workout, earn points |
| `log_food(...)` | Log food with macros |
| `search_food(query)` | Search Open Food Facts + USDA (400K+ foods) |
| `get_program_schedule()` | Today's scheduled workout |
| `redeem_reward(name)` | Spend points on a reward |
| `load_meal_plan(...)` | Create a meal plan |
| `get_meal_plan()` | View today's meals |
| `update_meal_compliance(...)` | Mark meals as followed/skipped |
| `get_plan_progress()` | Compliance stats |
| `configure_integration(...)` | Store encrypted credentials |
| `get_integration_status()` | Check provider connections |
See `AGENT_GUIDE.md` for behavioral guidelines including BREQ-2 tone calibration.
---
## What's inside
### Science-based onboarding
- **PAR-Q+** physical activity readiness screening
- **TTM** (Transtheoretical Model) stage assessment
- **BREQ-2** motivation profiling — the app adapts its tone to your motivation type
### Points engine
- Earn points for workouts, food logging, fasting, meal compliance
- Daily gate (minimum to unlock rewards)
- Weekly targets with reset
- Configurable reward shop — you decide what points are worth
### Integrations
Strava and Polar sync are built in. The provider registry supports Garmin, Fitbit, Withings, WHOOP, and Oura (OAuth flows ready, need provider approval). USDA FoodData Central for nutrition lookup.
---
## Project structure
```
Diligence/
pyproject.toml # pip install config
docker-compose.yml # Docker config
diligence/ # Python package
cli.py # Entry point for pip path
main.py # FastAPI app
config.py # Settings (auto-detects SQLite vs PostgreSQL)
database.py # Dialect-agnostic database layer
models/ # 15 SQLAlchemy models
routers/ # 12 API routers
services/ # Points engine, food lookup, sync, crypto
utils/ # Auth helpers
mcp/ # MCP connector (14 tools)
frontend/ # Pre-built React app (pip path serves this)
frontend/ # React source code
backend/ # Dockerfile + requirements.txt (Docker path)
mcp-connector/ # MCP Dockerfile (Docker path)
```
---
### Linux Setup
Install Docker Engine and Docker Compose via your distro's package manager, or install Docker Desktop for Linux. Then:
## Development
```bash
git clone https://github.com/diligenceworks/diligence
cd diligence
./setup.sh
docker compose up -d
# Clone
git clone https://github.com/DiligenceWorks/Diligence.git
cd Diligence
# Backend
pip install -e ".[dev]"
diligence --port 8000
# Frontend (separate terminal)
cd frontend
npm install
npm run dev
```
---
Open http://localhost and create your account. First user gets admin.
## Data and privacy
### Verify
Your data never leaves your machine. There is no telemetry, no analytics, no cloud sync. The database is a single file (`~/.diligence/data.db` for pip, a Docker volume for Docker). Back it up however you back up your files.
```bash
docker compose ps
```
Integration credentials (Strava, Polar, etc.) are encrypted at rest using Fernet with HKDF key derivation from your SECRET_KEY.
You should see 4 containers, all healthy: `frontend`, `backend`, `mcp-connector`, `fitness-db`.
## Features
- **Points economy** — earn from workouts, food logging, step goals. Daily gate locks rewards until you earn enough. Weekly reset.
- **Science-based onboarding** — PAR-Q+ safety screening, TTM stages of change, BREQ-2 motivation profiling.
- **AI agent integration** — 14 MCP tools for logging, coaching, meal planning, and device configuration.
- **Meal plans** — AI-generated plans with compliance tracking and points integration.
- **Activity sync** — Strava, Polar (OAuth 2.0). Garmin, Fitbit, Withings, WHOOP, Oura configurable in-app.
- **Food search** — Open Food Facts (4M+ products) + USDA FoodData Central (400K+ research-grade).
- **Program tracking** — 90-day structured programs (StrongLifts, Darebee, etc.) with day-by-day progression.
- **Configurable rewards** — you define what's worth earning. Gaming time, screen time, treats — your rules.
## Built-in AI Coach
Diligence includes a built-in AI coaching chat. Configure any LLM provider in **Settings → Integrations**, then open the **Coach** tab.
Supported providers (one API key, that's it):
| Provider | Free tier | What you get |
|----------|-----------|-------------|
| **OpenRouter** | 26 free models | 300+ models from every major provider, one key |
| **Hugging Face** | Yes | Thousands of open-source models |
| **Groq** | Yes | Ultra-fast Llama inference |
| **Ollama** | Local, free | Run any model on your own machine |
| **OpenAI** | No | GPT-4o, GPT-4o-mini |
| **Claude** | No | Claude Sonnet 4.6, Opus 4.8 |
| **Gemini** | Yes | Gemini 2.0 Flash, 2.5 Pro |
| **Custom** | — | Any OpenAI-compatible endpoint (vLLM, TGI, LiteLLM) |
The AI coach has access to your profile, points, program schedule, and motivation type. It can log workouts, search food, and create meal plans through the chat.
### Connecting external AI agents (MCP)
The MCP connector at port 3001 works with any MCP-compatible agent. The built-in chat and external agents coexist — use whichever fits your workflow.
**Claude Desktop** — add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"diligence": { "url": "http://localhost:3001/sse" }
}
}
```
**Claude Code** (CLI):
```bash
claude mcp add diligence --transport sse http://localhost:3001/sse
```
**Cursor** — add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"diligence": { "url": "http://localhost:3001/sse" }
}
}
```
**Windsurf** — add to MCP settings, same format as Cursor.
**COROS watch owners** — add both Diligence and COROS MCP servers to your agent. The agent bridges your watch data with your fitness log:
```json
{
"mcpServers": {
"diligence": { "url": "http://localhost:3001/sse" },
"coros": { "url": "https://your-coros-mcp-url/sse" }
}
}
```
Copy the contents of [AGENT_GUIDE.md](AGENT_GUIDE.md) into your agent's system instructions for motivation-aware coaching.
## Configuring Integrations
All integrations are configured through the app UI (**Settings → Integrations**) or through your AI agent. No `.env` file editing or container restarts needed.
Tell your agent: *"I want to connect my Strava"* — it will walk you through getting API credentials and store them encrypted.
## Data Sovereignty
Diligence is self-hosted software. Your data never leaves your server. No cloud dependency, no vendor lock-in, no telemetry. MIT license — fork it, modify it, keep it forever.
Your fitness data — heart rate, body composition, food intake, GPS traces — is biometric data that deserves sovereignty.
## Architecture
```
┌─────────────────────────────────────────────────┐
│ nginx │
│ (frontend, /api proxy, /mcp proxy) │
├──────────┬─────────────────┬────────────────────┤
│ React │ FastAPI │ MCP Connector │
│ SPA │ Backend │ (14 tools) │
│ │ │ port 3001 │
│ ├──────────────────┤ │
│ │ PostgreSQL 16 │ │
│ │ (internal only) │ │
└──────────┴──────────────────┴────────────────────┘
```
## Stack
- Python 3.12, FastAPI, SQLAlchemy (async)
- React 18, Vite
- PostgreSQL 16
- FastMCP (Streamable HTTP/SSE)
- Docker Compose
## Updating
```bash
git pull
docker compose build
docker compose up -d
```
Database migrations run automatically on startup. Your data is preserved.
## Backing Up
Your data lives in the `fitness_db_data` Docker volume:
```bash
docker compose exec fitness-db pg_dump -U fitness fitness_rewards > backup.sql
```
To restore:
```bash
docker compose exec -i fitness-db psql -U fitness fitness_rewards < backup.sql
```
## Contributing
Contributions welcome. Please open an issue to discuss before submitting a PR.
---
## License
MIT — see [LICENSE](LICENSE).
MIT. See `LICENSE`.
Built by [DiligenceWorks Pte. Ltd.](https://diligenceworks.online)