Skip to content
This repository was archived by the owner on Jul 18, 2026. It is now read-only.

DEVELOPER_GUIDE.md

Latest commit

 

History

History
104 lines (78 loc) · 3.61 KB

DEVELOPER_GUIDE.md

File metadata and controls

104 lines (78 loc) · 3.61 KB
Raw

Developer guide

Repository layout

backend/                 Django REST API and domain apps
frontend/                React/Vite client, unit and browser tests
docs/                    Product, engineering and release documentation
.github/workflows/       CI and browser-test workflows
docker-compose.yml       Loopback-bound local development stack
.env.example             Local example and production variable catalogue

Backend setup

Use Python 3.12 or newer. The automated workflows use Python 3.13.

From backend/:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Create a PostgreSQL database and configure the root .env as described in CONFIGURATION.md, then:

python manage.py migrate
python manage.py seed_demo
python manage.py runserver 127.0.0.1:8000

Management commands of note:

  • seed_demo — idempotently seed fictional local data.
  • reset_demo_data --confirm RESET_DEMO_DATA — delete the entire fixed example-pharmacy-group (including extra records or memberships added to that group), delete the known demo users, and reseed the synthetic workspace.
  • seed_catalogue — seed the small built-in catalogue fixture.
  • import_dmd / import_trud_dmd — optional local reference-data imports; inspect --help and keep source files/credentials outside version control.
  • generate_backup_key — print a fresh backup archive key for secure storage.
  • run_scheduled_backups — run due schedules; invoke it from a separately configured scheduler such as cron rather than assuming the UI runs a daemon.

Frontend setup

Use Node.js 22.13 or newer and npm. From frontend/:

npm ci
API_PROXY_TARGET=http://localhost:8000 npm run dev

Vite serves http://localhost:5173 and proxies /api to the configured target. Set VITE_API_BASE_URL at build time only when the deployed frontend should call an explicit API origin.

Design boundaries

  • Put permission and scope enforcement in the backend, not only in UI guards.
  • Use service functions and database transactions for multi-record mutations.
  • Record stock changes through movement-generating workflows.
  • Keep analytics deterministic, explainable and explicitly non-ML.
  • Use synthetic fixtures with reserved domains and fictional addresses.
  • Do not put secrets, downloaded reference archives, exports or generated backups in the repository.
  • Treat Dosette print output as a preparation aid requiring human review.

Schema changes

From backend/:

python manage.py makemigrations
python manage.py migrate
python manage.py makemigrations --check --dry-run

Review generated operations and test both forward migration and a representative restore path. Do not edit historic migration meaning merely to silence drift.

API and frontend changes

Update serializers, views, permissions and tests together. For frontend data access, keep endpoint calls in feature API modules and use TanStack Query keys that include relevant scope/filter parameters. Handle 401/403 and validation responses without revealing sensitive payloads.

Quality checks

Follow TESTING.md. A failed mypy or clean-install build must remain visible even when other suites pass. Format or lint only the files in scope when preparing a focused change.

Commit and review hygiene

Use an imperative conventional subject and a body that names changed paths and purpose. Keep generated artefacts out of commits. Review git diff --check, the staged diff, and repository status before committing. See ../CONTRIBUTING.md.