# Project pack: Baby Buddy @ 09629cf

Facts about **Baby Buddy** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Baby Buddy helps new parents and carers keep track of feeds, sleep, nappy changes, tummy time, medicine, weight and more. Timers make it quick to log things at 3am, and charts show patterns over days and weeks, so you can see when your baby is likely to be hungry or tired. Everyone who looks after the baby can share it. It runs on your own computer or server, so your family's data stays private.

## Version and source
- Repository: https://github.com/babybuddy/babybuddy
- Pinned commit: `09629cf633cf3a2059a21ade4cea7ea4d846422f`. Use exactly this version.
- Get it: `git clone https://github.com/babybuddy/babybuddy babybuddy && cd babybuddy && git checkout 09629cf633cf3a2059a21ade4cea7ea4d846422f`
- Or download a zip: https://github.com/babybuddy/babybuddy/archive/09629cf633cf3a2059a21ade4cea7ea4d846422f.zip
- Official docs: https://docs.baby-buddy.net
- Live demo: https://demo.baby-buddy.net (username: admin / password: admin). Public demo; it resets every hour. Don't enter real data.
- Licence: **BSD-2-Clause**. Free to use, change and share for any purpose, including commercially. Just keep the copyright notice and licence text with the code. You don't have to publish your changes.

## Running it
- Easiest: docker run -d --name babybuddy -p 8000:8000 -v babybuddy-config:/config --restart unless-stopped lscr.io/linuxserver/babybuddy # then open http://localhost:8000, log in as admin / admin and change the password straight away
- Needs: Docker, or for development Python 3.10+ with pipenv, Node.js 24 with npm, and gulp-cli (or use the included dev container)
- Develop: `pipenv install --dev && npm install && export DJANGO_SETTINGS_MODULE=babybuddy.settings.development && gulp migrate && gulp   # http://127.0.0.1:8000, admin / admin`
- Test: `gulp test`
- Check/lint: `gulp lint`
- Stack: python, javascript, html, scss (Django 5, Django REST Framework, Bootstrap 5, Plotly, Gulp). Difficulty for a non-developer with an AI: **easy**. A classic Django project with server-rendered templates and a few small apps (core, dashboard, reports, api, webhooks). Most changes are a model, a view, a template, a dashboard card or a chart. Gulp builds the styles and runs the dev server.

## Customisation points (settings → extend → code)
- **user-settings** [settings]: Language (25+ languages), time zone, dashboard refresh rate and which cards to hide. → `User settings page /user/settings/ (fields in babybuddy/models.py)`
- **site-settings** [settings]: The hours when a sleep counts as a nap, and other household-wide defaults. → `Site settings at /settings/ (babybuddy/site_settings.py)`
- **carers-and-tags** [settings]: Give a partner, grandparent or nanny their own login; read-only for family who just want to look, caregiver for a babysitter. → `Users page with Read only and Caregiver roles (babybuddy/forms.py, docs/user-guide/managing-users.md); tags on entries`
- **api-and-webhooks** [extend]: Log feeds from a button or smart speaker, or tell another app when something is recorded. → `REST API under /api/ with a token from user settings (api/); webhooks in Database Admin, sent by the deliver_webhooks command (webhooks/)`
- **import-export** [extend]: Move data in from another baby app or out to a spreadsheet. → `Database Admin import and export (django-import-export; docs/import-export.md)`
- **dashboard-and-charts** [code]: New dashboard cards or charts, such as feeds per day this week. → `dashboard/templatetags/cards.py and dashboard/templates/cards/, reports/graphs/ (Plotly charts)`
- **models-and-pages** [code]: New things to track or changes to forms. Database changes need a Django migration. → `core/models.py, core/views.py, core/templates/, babybuddy/static_src/scss/ (look)`

## Must keep working
- Existing children and all their entries. Back up the database and photos first.
- Database changes need a new migration (gulp makemigrations); never edit old ones.
- Permissions for read-only and staff users.
- The /api/ endpoints, which phone apps, Home Assistant and hardware projects depend on.

## Staying updatable
User and site settings, the API, webhooks and import/export cover many needs without a fork, and a wide range of community apps, Home Assistant add-ons and hardware already build on the API. Keep code changes small and inside one app.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite database and uploaded photos in the /config volume (Docker); PostgreSQL or MySQL optional. Children's names, birth dates, health measurements and medicine are sensitive family data. Back up the config folder before upgrades or code changes. Staff users can export each type of entry from Database Admin.
- Service: Email (SMTP) (optional, free with most providers): Password resets.
- Service: S3-compatible storage (optional, pay-per-use): Store child photos outside the server.
- Service: Home Assistant (optional, free (self-hosted)): Host Baby Buddy as an add-on and show its data on smart-home dashboards (community add-on and integration).
- Setting `SECRET_KEY` (**secret**: the person enters it themselves, never in chat): Long random string that protects logins. The Docker image makes one for you; set your own for other installs. Never paste it into an AI chat.
- Setting `ALLOWED_HOSTS`: The web addresses Baby Buddy may be reached at, e.g. baby.example.org.
- Setting `CSRF_TRUSTED_ORIGINS`: Your full address with https:// when behind a reverse proxy, or forms will fail to save.
- Setting `DB_ENGINE`: Database type (SQLite by default). DB_HOST, DB_NAME, DB_USER, DB_PASSWORD and DATABASE_URL set the connection.
- Setting `ALLOW_UPLOADS`: Whether photos can be uploaded (for example, a photo of each child).
- Setting `ENABLE_HOME_ASSISTANT_SUPPORT`: Set to True only when running through Home Assistant's ingress.
- Change the default admin / admin password immediately after first login.
- Use HTTPS before exposing it to the internet; it holds children's health data.
- Not a medical device. Talk to a health professional about anything worrying.

---

# Customising Baby Buddy

Baby Buddy is a straightforward Django app, and **most family needs are covered by settings and the API**. It is also one of the easier projects to change in code.

## Level 1: Settings (no code)
- **Your settings** (`/user/settings/`): language (25+ languages), time zone, how often the dashboard refreshes, and which empty or old cards to hide.
- **Site settings** (`/settings/`, defined in `babybuddy/site_settings.py`): the hours when a sleep counts as a nap.
- **People:** add a login for each carer. Choose **Read only** for family who just want to look, or **Caregiver** for a babysitter who can add entries but not delete them (see `docs/user-guide/managing-users.md`).
- **Tags** on entries, e.g. "teething" or "growth spurt", to find them later.
- **Server options:** environment variables such as `ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`, `DB_ENGINE`, `ALLOW_UPLOADS` and the `EMAIL_*` values (docs in `docs/configuration/`).

## Level 2: Extend (no fork)
- **REST API** under `/api/` (e.g. `/api/feedings/`, `/api/changes/`) with a token from your user settings. Smart buttons, Home Assistant, iPhone shortcuts and Alexa skills already use it.
- **Webhooks:** add endpoints in Database Admin (or via `/api/webhook-endpoints/`) and run `python manage.py deliver_webhooks` on a schedule. Each request says what changed; the receiver reads details back through the API.
- **Import and export:** staff users can export or import each entry type from Database Admin (`docs/import-export.md`).
- **MCP:** the separate `babybuddy/babybuddy-mcp` server lets an AI assistant log and query entries.

## Level 3: Code
| Change | Where |
|---|---|
| Things you track (feeds, sleep, nappies…) | `core/models.py`, forms in `core/forms.py`, views in `core/views.py`, templates in `core/templates/core/` |
| Dashboard cards | `dashboard/templatetags/cards.py` + `dashboard/templates/cards/` |
| Charts | `reports/graphs/` (Plotly) |
| API | `api/` |
| Look | `babybuddy/static_src/scss/` (`_variables.scss` for colours) |
| Text | `locale/` (translations are managed through POEditor) |
| New data | edit the model, then `gulp makemigrations` |

## Running locally
- **Just use it:** `docker run -d -p 8000:8000 -v babybuddy-config:/config lscr.io/linuxserver/babybuddy`, then open http://localhost:8000, log in as `admin` / `admin` and change the password.
- **Develop** (or open the repo in the included dev container and run `gulp`):
  1. Install Python 3.10+, pipenv, Node.js 24 and `npm install -g gulp-cli`.
  2. `pipenv install --dev` and `npm install`.
  3. `export DJANGO_SETTINGS_MODULE=babybuddy.settings.development`
  4. `gulp migrate`, then `gulp` (builds assets and runs the server).
  5. Open http://127.0.0.1:8000.
- **Check:** `gulp lint`, `gulp test`. `gulp fake` adds made-up data to play with.

## Pitfalls
- Back up the database and photos first. A baby's first months can't be recorded again.
- Change the default `admin` / `admin` password on every install.
- Caregivers can see every child on the instance; there is no per-child access.
- Phone apps, Home Assistant and hardware projects rely on the `/api/` shape. Don't break it.
- It's a tracker, not medical advice.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/babybuddy/09629cf/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/babybuddy/09629cf/SKILL.md)