Animals Healthcare Application

A Django monolith for managing pet health data — medical timelines, diet logs, biometric records, and scheduled notifications.

Overview

Pet owners and carers register animals and maintain detailed health records.

Selective access can be shared with other users per data category (vet contact, diet, medications, vaccination history, biometrics). The core of the app is a unified medical timeline, filterable by note type and tag. Scheduled reminders for upcoming visits and vaccinations are delivered via Discord.

Features

• Animal profiles with configurable per-category sharing between owners and carers.
• Medical timeline filtered by note type (visit, diet, medication, vaccination, biometric) and tag.
• Inline-editable vaccination records with date-based Discord reminders.
• Biometric tracking (weight, height, custom measurements) with historical charts planned.
• Diet plan management with recurring e-mail / Discord notification schedules.
• Attachment storage for medical documents via CouchDB.
• Async task processing (Celery Beat + Redis) for scheduled notifications.

Requirements

• Python 3.14
• uv — package manager
• just — task runner (optional)
• Docker Desktop / Docker + Compose
• PostgreSQL 18 (managed via Docker)
• Apache CouchDB 3.3.3 (managed via Docker)
• Redis 7 (managed via Docker)

Environment Variables

Copy .env.template to .env and fill in the values — all required variables and their descriptions are documented in the template file.

Getting Started

Docker Deploy

1. Clone the repository.
2. Set up the .env file based on the provided template.
3. Start all services:

   docker compose -f docker/docker-compose.yml up -d --build

The stack exposes: Django app on :8000, Flower (Celery monitor) on :5555.

Dev Instance

1. Clone the repository.
2. Set up the .env file based on the provided template.
3. Install uv and sync dependencies:

   pip install uv
   uv sync

4. Register pre-commit hooks:

   uv run pre-commit install

5. Start the dev server (starts backing services, applies migrations, runs Django):

   just dev

   Or without just:

   docker compose --env-file .env -f docker/docker-compose.yml up -d --wait postgres_db redis couch_db
   uv run python manage.py migrate
   uv run python manage.py runserver

Kubernetes Deploy (alternative)

An alternative to Docker Compose for production-like environments. See kubernetes/ for kustomization files and secret templates. Build and load images, then apply with kubectl apply -k kubernetes/.

Testing

Unit tests

uv run pytest -m unit
# or
just test-unit

Integration tests

Requires Docker backing services running (just infra).

uv run pytest -m integration
# or
just test-integration

All non-slow tests

just test

Linting

Check

uv run ruff check .
uv run ty check
uv run codespell
uv run bandit -r src -c pyproject.toml -q
# or
just lint

Format (auto-fix)

uv run ruff format .
uv run ruff check --fix .
# or
just format

Pre-commit hooks

Linting runs automatically on every git commit once hooks are installed (see Dev Instance step 4). To run manually against all files:

uv run pre-commit run --all-files
# or
just precommit

Screenshots

Click on an image to view full-size.

Animal profile	Full timeline of notes
Diet note details	User registration

Architecture Decisions

Key decisions are documented as ADRs in doc/:

ADR	Status	Topic
01	In progress	Core functionality scope
02	Done	Web framework — Django
03	Done	Architecture — monolith
04	Done	Repository structure — monorepo + GitHub Flow
05	Proposed	Charts — Matplotlib → Chart.js
06	Done	CSS framework — PicoCSS
07	Proposed	API framework — DRF
08	In progress	Databases — PostgreSQL + CouchDB + Redis
09	In progress	Data model — Animal fields and sharing
10	In progress	Notifications — Celery Beat + Background Tasks
11	Done	Frontend interactions — htmx + native <dialog>

Useful Links

• PicoCSS — CSS framework
• htmx — frontend interactions
• Celery — async task queue
• uv — package manager
• devs-mentoring.pl — mentoring programme