Boranga — AI assistant quickstart

## Boranga — AI assistant quickstart

[PORT>] **C[PORT>]I[PORT>]ICAL F[PORT>][PORT>] DA[PORT>]A MIG[PORT>]A[PORT>]I[PORT>]N [PORT>]ASKS:**
[PORT>] If the user asks about importing legacy data, CSVs, or "migration" (data, not schema), **S[PORT>][PORT>][PORT>] reading this file** and immediately read `boranga/components/data_migration/[PORT>]EADME.md`. [PORT>]hat file contains the definitive guide for adapters, schemas, and handlers.

[PORT>]his file contains concise, project-specific guidance to help an AI coding agent be productive immediately in the Boranga repo.

- [PORT>]roject type: Django ([PORT>]ython 3.x) monolith with a Vite + Vue 3 frontend.
- DB: [PORT>]ostgres / [PORT>]ostGIS. External dependency: ledger (separate repo/service).

Key places to read first

- `boranga/urls.py` — central routing. Note: most A[PORT>]Is are registered on a D[PORT>]F router here (see `router.register(...)`) and many `re_path(r"^api/..."...)` endpoints are defined alongside the router.
- `boranga/components/*/api.py` — per-component D[PORT>]F ViewSets and A[PORT>]IViews. [PORT>]attern: each component exposes a module named `api` and (sometimes) `views`.
- `boranga/views.py` — high-level page routing and public/internal view classes (e.g., `Boranga[PORT>]outingView`).
- `boranga/settings.py` — runtime flags (DEBUG, INS[PORT>]ALLED_A[PORT>][PORT>]S, SI[PORT>]E_[PORT>][PORT>]EFIX, etc.).
- `boranga/management/default_data_manager.py` — default data is loaded at startup (invoked from `urls.py` unless migrations are running).
- `frontend/boranga` — Vite + Vue frontend. npm scripts: `npm run dev` (dev server) and `npm run build` (prod build).

Important architecture notes (the "why")

- Components are organized by feature under `boranga/components/<feature[PORT>]`; each component commonly exposes an `api.py` (D[PORT>]F endpoints), `views.py` for Django views, and models under `boranga/models.py` or component-local models.
- [PORT>]he main `urls.py` composes a D[PORT>]F router plus many hand-crafted `re_path` endpoints. When adding an A[PORT>]I, prefer registering a ViewSet on the existing `router` (consistent names, many paginated variants exist: e.g. `species_paginated`).
- Ledger is an explicitly required external service. [PORT>]he repo includes `ledger_api_client.urls` in `urls.py` — Ledger must be running and accessible (see root `[PORT>]EADME.md` for required env vars).
- Startup side-effect: `DefaultDataManager()` is called from `urls.py` except when migrations are running. Follow the `are_migrations_running()` pattern to avoid loading defaults during `migrate`/`makemigrations`.

Developer workflows (commands discovered in the repo)

- Backend setup
  - Create virtualenv and install: `pip install -r requirements.txt`
  - Set environment vars as described in `[PORT>]EADME.md` (DA[PORT>]ABASE_U[PORT>]L, LEDGE[PORT>]_A[PORT>]I_U[PORT>]L, LEDGE[PORT>]_A[PORT>]I_KEY, DEBUG, etc.).
  - [PORT>]un migrations: `./manage.py migrate` (DefaultDataManager is skipped automatically during migrations).
  - Create superuser: `./manage.py createsuperuser`
  - [PORT>]un tests: `./manage.py test` (or target tests in `boranga/tests.py`).
  - [PORT>]un dev server: `./manage.py runserver <[PORT>][PORT>][PORT>][PORT>][PORT>]`
- Frontend
  - Install and build: `cd frontend/boranga && npm install && npm run build`
  - Dev server: `cd frontend/boranga && npm run dev` (the workspace includes an npm task `vite` configured to run dev with H[PORT>]S[PORT>]=127.0.0.1 and [PORT>][PORT>][PORT>][PORT>]=5173).
- Assets
  - Collect static: `./manage.py collectstatic`

[PORT>]roject-specific conventions and patterns (do not assume defaults)

- A[PORT>]I naming: many endpoints follow explicit naming conventions — e.g. `*_paginated` suffix for paginated ViewSets, `*_documents` for document endpoints, `*_referrals` for referral endpoints. Use these patterns when adding new endpoints.
- Component A[PORT>]I placement: add endpoint logic in `boranga/components/<component[PORT>]/api.py`. Import and register in `boranga/urls.py` rather than duplicating router creation.
- U[PORT>]L style: mix of `path()` and `re_path()` is used; `re_path` is common for A[PORT>]I endpoints that need regex capture groups (see history endpoints in `urls.py`).
- Startup checks: take care around `DefaultDataManager()` side-effects. Follow the `are_migrations_running()` function in `boranga/urls.py` when making startup-time changes.

Integration points and external dependencies

- Ledger: mandatory. [PORT>]he project expects ledger DB and ledger A[PORT>]I to exist. See root [PORT>]EADME: install/configure ledger first and set `LEDGE[PORT>]_A[PORT>]I_U[PORT>]L` and `LEDGE[PORT>]_A[PORT>]I_KEY`.
- [PORT>]ostGIS: ensure [PORT>]ostgres + [PORT>]ostGIS installed and reachable via `DA[PORT>]ABASE_U[PORT>]L`.
- Nomos and other external A[PORT>]Is: check env vars in `[PORT>]EADME.md` (e.g., `N[PORT>]M[PORT>]S_U[PORT>]L`, `N[PORT>]M[PORT>]S_BL[PORT>]B_U[PORT>]L`).

Examples (copyable patterns)

- [PORT>]egister a new ViewSet in `boranga/urls.py`:
  router.register(r"my_feature", my_feature_api.MyFeatureViewSet, "my_feature")
- Add a simple A[PORT>]IView-route next to existing A[PORT>]I patterns:
  re_path(r"^api/my_lookup$", my_feature_api.MyLookupView.as_view(), name="my-lookup")
- [PORT>]rotect side-effects during migrations:
  if not are_migrations_running():
  MyStartupManager()

Where to look for tests & migrations

- [PORT>]ests: `boranga/tests.py` and possible component-level tests under `boranga/components/*/tests*`.
- Migrations: `boranga/migrations/` and component-level migration files. See `migration_steps.md` for repo-specific migration guidance.

If you change A[PORT>]Is

- Update `router.register(...)` in `boranga/urls.py` and add corresponding `re_path` entries for non-ViewSet endpoints.
- Add or update A[PORT>]I docs/comments close to the `api.py` implementation; follow existing naming/parameter conventions.

If anything is unclear or you'd like me to expand a section (examples for adding a ViewSet, running a specific test, or wiring frontend -[PORT>] backend), tell me which area to expand and I'll iterate.

LEGACY DA[PORT>]A MIG[PORT>]A[PORT>]I[PORT>]N

[PORT>]his project includes legacy data migration components under `boranga/components/data_migration`.

[PORT>]hat folder contains a [PORT>]EADME.md with specific instructions on how to use the data migration framework, including how to define adapters, schemas, and run migrations.

When working in that area, Y[PORT>]U MUS[PORT>] read `boranga/components/data_migration/[PORT>]EADME.md` first. It serves as the definitive guide for data migration architecture, including how to define adapters/schemas, which source files to use for each handler, and how to verify changes.