Buddy

Buddy is a family coordination tool for parents and guardians of children with ADHD. It provides shared calendars, medication tracking with dose status, and family meal and pickup planning, all designed around the core insight that kids with ADHD often struggle less with knowing what to do than with keeping track of when and what's next. Guardians can plan structure and daily routines, while children see a personalized day view that helps them stay on track.

Why Buddy

The challenge isn't usually knowing "I need to take this medicine" or "we're eating dinner"—it's remembering when, and then actually doing it. Buddy is built around that reality: shared calendars for events and tasks, structured medication schedules with daily dose tracking, and a family meal library so guardians can plan meals once and have them show up for every child. Pickup and drop-off schedules make responsibility explicit, including guardian, sibling, self-escort, and playdate arrangements. The child gets a clear, interactive view of their day; the guardian gets visibility and the ability to adjust plans in real time.

Features

Guardian

• Social stories: short illustrated stories, linked to a calendar event, that prepare a child for something new such as the dentist or a trip (proposed, not yet implemented — see Social stories)
• Guided setup for guardians with no groups or children: one group, children, optional invitations, a shared calendar, a first routine and a meal plan, resumable and deferrable (see Guardian onboarding)
• Create child accounts and manage guardian/child relationships, including resetting a child's password (children have no email for a self-service reset)
• Shared calendars: day, work-week, rolling-week, and month views, with event/task creation across personal and group-owned calendars
• Medicine schedules with daily dose times and dose-status tracking
• Family meal library and meal-plan assignment, with meal ratings and group-shared meal plans
• Private iCal subscription links for the family's meal plan
• Chat-based AI assistant that drafts meal-plan assignments, with BYOK AI provider settings management
• Limit the meals sent to the AI assistant to rated meals and/or meals served in the last 30/60/90 days
• Import historical meal plans from notes and CSV files, with review and undo
• Pickup and drop-off scheduling (guardian, sibling, self-escort, playdate, and babysitter assignments)
• Reusable task library with ordered, timed subtasks, schedulable onto a calendar
• Group and calendar sharing/permissions management
• Configurable goal posts and gamified progress tracking for children
• Profile, calendar, group, child, and account administration
• Sleep diary logging for children, with a revocable, expiring share link that lets a doctor read a printable 14-day view without an account
• Printable A3/A4 landscape week plans from saved, shareable templates
• Guardian work locations with alternating weekly patterns and per-day exceptions
• Saved babysitters/nannies for pickup and drop-off
• In-app help: a help panel on every guardian page and a help index, in English and Danish
• House rules for a household (group) and for each child, written in markdown, which children read and acknowledge, and which print on A4 for the fridge
• Calling names: a guardian can choose what their children call them ("Mom", "Far"), shown instead of their first name on the child's home page and the printed week plan
• Medicine effect and side-effect notes: daily ratings of focus, calm, impulses and mood and of side effects, linked to the dosage the child was on, with a by-dose-period summary for dose-adjustment conversations (see Medicine effect and side-effect notes)
• First–Then board: a guardian pairs a non-preferred task with a preferred activity ("first homework, then iPad"), and the child ticks off the first card to unlock the second, with an optional countdown — see First–Then board
• Skip one occurrence of a repeating appointment or task on a single day, without changing or ending the series, and restore it again — see Skipping single occurrences
• Per-item alarms (VALARM) in the calendar iCal feed, for subscribing calendar apps (see Calendar item alarms)
• Doctor visit summary: one printable A4 report of sleep, doses, effect notes and feelings for a chosen period of at most 92 days, with one revocable, expiring doctor share link (see Doctor visit summary)
• Draft and publish house rules: guardians write and refine a rule before the children see it, then publish one rule or all drafts at once (see House rules publishing)
• Mark meals as eating out (at friends/family or a restaurant), so the AI assistant never suggests them and leaves those slots alone
• Leave medicines out of the effect summary: switch off medicines such as vitamin D in the dose-period summary; the doctor visit summary drops them and says how many were left out (see Leaving medicines out of the effect summary)
• Mealie integration: connect the family's self-hosted Mealie, link meals to recipes, import Mealie's meal plan and send the week's recipes to a Mealie shopping list (see Mealie integration)
• Private iCal subscription link with the pickups and drop-offs a guardian is assigned to, across all their children, with a reminder before each timed slot (see Pickup iCal feed)

Child

• Now / Next / Later strip: a reduced day view with three cards for overwhelmed moments (proposed, not yet implemented — see Now / Next / Later strip)
• Personalized day view: meals and ratings, medicine doses, pickup/drop-off assignments, and tasks
• Read-only seven-day calendar agenda
• Browse current and previous meal-plan weeks and rate meals
• View linked guardians
• Complete tasks from the day view
• View progress and unlocked milestones
• Spend stars on guardian-defined rewards, approved by a guardian
• Visual time-left timer on the current routine and subtask, with a focus view, that a guardian can turn off per child — see Visual time-left timer
• Transition warnings before events, tasks and pickups: a countdown on the child's screen, off until a guardian turns it on per child — see Transition warnings
• Feelings check-ins: the child taps a colour and a face (faces only for a young child), a guardian logs observations and sees a 14-day trend next to sleep and doses, with reminder times and a doctor share link — see Feelings check-in
• Weekday packing checklists on the day view, shown the evening before, one star per packed list, with guardian-approved child suggestions, copying a template to a sibling and an evening "Packing for tomorrow" dashboard card — see Packing checklists
• Homework splitter: the child splits tonight's homework into timed focus chunks with breaks and break ideas, using focus and break lengths a guardian sets per child — see Homework splitter
• Pictograms: in-house picture symbols on tasks, routine steps and First-Then boards for children who don't read yet (see Pictogram support)
• The screen stays on, and the session alive, while a child's timer runs, so a long timer neither dims the iPad nor signs the child out — see Keep the screen awake

Platform

• Keycloak authentication, token lifecycle, and role-based routing by Keycloak group: only buddy-guardian members see the guardian pages and only buddy-child members the child board; an account in neither group can't use Buddy
• Group and guardian invitations and email-verification flows; an invitation can only be accepted by an account with a verified email address that matches the invited one
• English and Danish localization
• Light, dark, and system theme selection
• Per-user and per-feed rate limiting on every API endpoint
• GDPR: account and child erasure, data export, AI data minimization and retention, and health-data read audit logs. What you still have to do when you run Buddy is in PRIVACY.md
• Per-installation feature flags to turn optional features off
• Installable mobile app (PWA) with push notifications for reward requests, completed tasks, milestones, missed doses and reminders (proposed, not yet implemented — see Mobile app and push notifications and Buddy as a mobile app)
• Versioned multi-arch Docker images (amd64 and arm64) published to the GitHub Container Registry on every release
• Software bills of materials (SBOMs) for the backend, frontend and every published image, attested in GHCR and attached to each GitHub release

Repository structure

src/
  backend/   .NET API with event-sourced aggregates, Marten/PostgreSQL storage,
             and Keycloak-backed authentication
  frontend/  Angular application for guardians and children
  load-tests/ k6 performance and load tests against an isolated, production-sized stack
docs/
  backend/   Backend glossary, flow docs, HTTP semantics, and design analyses
  frontend/  Frontend architecture, feature status, and design analyses
agents/      Reusable agent skills, examples, templates, and samples
deploy/      Production Docker Compose and Caddy deployment

• Architecture — C4 context and container diagrams.
• Backend documentation — domain glossary, user flows, HTTP semantics, and design analysis documents.
• Frontend documentation — Angular app shell, auth flow, feature layout, and current product status.
• Development container — local services, environment setup, ports, and first-run Keycloak configuration.
• Git hooks — opt-in pre-commit format/lint checks and a post-commit hook that uses Claude, Codex, or GitHub Copilot to keep docs/, this README and TODO.md in sync with commits.
• Screenshots — every page of the app with demo data; regenerate with task docs:screenshots.
• Testing — commands for frontend, backend, mutation and load test suites.
• Installation — how to install your own Buddy, and every setting and command-line argument it takes.
• Deployment — production Docker Compose and Caddy setup.
• Privacy and GDPR — what Buddy does with children's data, and the checklist for anyone who runs it.
• Versioning — release tags (v1.2.0) and how the version reaches the API (GET /version) and the frontend.
• Agent packages — reusable coding and documentation skills.
• Backend app guide — running, configuring, and laying out the API implementation.
• Frontend app guide — running, configuring, and laying out the Angular frontend.
• docs/README.md — the documentation landing page.

Core concepts

• User — an authenticated person (guardian or child), backed by Keycloak for authentication and modeled locally as an event-sourced aggregate with profile and email state. See the glossary.
• Calendar — a scheduling container of events and tasks, owned by a user or a group, with per-member roles such as Owner, Contributor, and Viewer.
• Group — a collection of users, such as a family, with roles such as Owner, Admin, and Member, allowing shared ownership and permission mapping across calendars. See Group-owned calendars and permissions.
• Guardian/child relationships — how a guardian is linked to a child's account and what that grants them. See Child accounts and guardian/parent roles.
• Medicine schedule — a child-facing medication routine with daily dose times, dose tracking, and per-dose Taken / Skipped states. See Medicine schedules.
• Meal plan — a family meal library and daily slot assignments for breakfast, lunch, dinner, and snacks, with meal rating and archival functionality.
• Pickup schedule — a per-child weekly plan for pickup and drop-off slots, with explicit guardian, sibling, self-escort, playdate, and babysitter assignments. See Pickup and drop-off schedules.
• Babysitter list — each guardian's saved babysitters and nannies, which any of a child's guardians can pick for a pickup slot. See Babysitters.
• Task library — a child-specific collection of reusable task templates with ordered, timed subtasks that a guardian can schedule onto a calendar. See Task Library flow.

Documentation map

Backend docs

• Users flow
• Calendars flow
• Groups flow
• Guardians flow
• Medicines flow
• Mealplans flow
• Pickups flow
• Babysitters flow
• Task Library flow
• Progress flow
• Glossary
• HTTP status code semantics
• Health checks and observability

Design analyses

• GDPR: erasure, export and data minimization
• Group-owned calendars and permissions
• Aggregate roots and their relationships
• All-day calendar items
• Integration testing strategy
• Mutation testing strategy
• Performance and load testing with k6
• Validation rules
• Child accounts and guardian/parent roles
• Guardian-managed child language
• Calling names for guardians
• Guardian-managed child time zone
• Medicine schedules
• Meal plans
• Group-shared meal plans
• Meal plan iCal feed
• Importing historical meal plans
• AI assistant meal filter
• Mealie integration
• Pickup and drop-off schedules
• Pickup iCal feed
• Babysitters
• Gamified progress

Installing Buddy

To run Buddy for a family, install it on a server of your own (or on Azure Container Apps). Once it is running, the first guardian who signs in gets a guided setup in the app.

• What you need: a Linux server (amd64 or arm64, 2 CPUs and 4 GB of memory or more) with Docker, the compose plugin, git and Task; a domain with DNS records for app., api. and auth.; and an SMTP account for invitation and verification emails.
• Published images: every release is published to the GitHub Container Registry as ghcr.io/kimipsen/buddy-api, buddy-frontend and buddy-keycloak, for amd64 and arm64. Check out the release tag and run task deploy:pull. To build the images on the server instead (for a fork), run task deploy.
• Settings: copy deploy/.env.example to deploy/.env and fill in the server's hostname, the three domains, the PostgreSQL and Keycloak admin passwords and the Mail__* settings. Optional lines turn off features this family doesn't use (Features__Medicines=false).
• First Keycloak setup: sign in at https://auth.<your domain> as the admin, import the buddy realm and point its buddy-frontend client at your app's domain. Then put a new buddy-admin-cli secret in .env and create the first guardian account in the buddy-guardian group.

The installation guide has the steps in full, plus every setting and command-line argument. The VM deploy guide covers one server in depth, including backups, upgrades and rollback, and the Azure deploy guide covers Azure Container Apps.

Getting started

To work on Buddy's code, use the development environment below. The supported local environment is the VS Code development container. It provides .NET, Node, npm, Angular CLI, Docker, PostgreSQL tooling, and the service network expected by the checked-in development configuration.

1. Create the local environment file before opening the container:

cp .devcontainer/.env.example .devcontainer/.env

2. Open the repository in VS Code and run Dev Containers: Reopen in Container. On a first run, complete the PostgreSQL and Keycloak setup in the development container guide; the current Compose file does not create the keycloak database or import the buddy realm automatically.

3. Start the backend:

cd src/backend/buddy
dotnet run

See the backend app guide for configuration details and project layout.

4. In another terminal, install dependencies and start the frontend:

cd src/frontend/buddy
npm install
npm start

The frontend is available at http://localhost:4300. See the frontend app guide for build and runtime configuration details, and the testing guide for test commands.

License, security and contributing

Buddy is released under the MIT License. To report a security problem, follow SECURITY.md; please don't open a public issue. To contribute, see CONTRIBUTING.md and the code of conduct.