Boranga Django Development Assistant

You are an AI assistant specialized in the Boranga codebase, a Django monolith with Vue 3 frontend. This skill provides project-specific context to help you be immediately productive.

Project Overview

Critical Entry Points

Before making changes, familiarize yourself with these key files:

1. **`boranga/urls.py`** — Central routing hub. DRF router + explicit `re_path()` API endpoints

2. **`boranga/components/*/api.py`** — Per-component DRF ViewSets and APIViews

3. **`boranga/views.py`** — High-level page routing and view classes

4. **`boranga/settings.py`** — Runtime configuration and feature flags

5. **`boranga/management/default_data_manager.py`** — Startup data loader (called from urls.py)

6. **`frontend/boranga`** — Vue 3 frontend with Vite build system

Architecture Principles

Component Organization

- `api.py` — DRF endpoints

- `views.py` — Django views

- Models (in `boranga/models.py` or component-local)

API Patterns

- `*_paginated` suffix for paginated ViewSets

- `*_documents` for document endpoints

- `*_referrals` for referral endpoints

Startup Behavior

Development Workflows

Backend Setup

```bash

Create virtualenv and install dependencies

pip install -r requirements.txt

Set required environment variables (see README.md)

DATABASE_URL, LEDGER_API_URL, LEDGER_API_KEY, DEBUG, etc.

Run migrations

./manage.py migrate

Create superuser

./manage.py createsuperuser

Run tests

./manage.py test

Start dev server

./manage.py runserver <PORT>

```

Frontend Setup

```bash

cd frontend/boranga

Install dependencies

npm install

Development server (HOST=127.0.0.1, PORT=5173)

npm run dev

Production build

npm run build

```

Static Assets

```bash

./manage.py collectstatic

```

Common Tasks

Adding a New API Endpoint

**For ViewSets (preferred):**

```python

In boranga/components/<component>/api.py

class MyFeatureViewSet(viewsets.ModelViewSet):

# Implementation

In boranga/urls.py

router.register(r"my_feature", my_feature_api.MyFeatureViewSet, "my_feature")

```

**For APIViews:**

```python

In boranga/urls.py

re_path(r"^api/my_lookup$", my_feature_api.MyLookupView.as_view(), name="my-lookup")

```

Protecting Startup Side Effects

```python

Follow this pattern in urls.py

if not are_migrations_running():

MyStartupManager()

```

External Dependencies

Ledger (Required)

PostGIS (Required)

Other APIs

Data Migration (CRITICAL)

**⚠️ STOP: If the user mentions "data migration", "importing legacy data", "CSVs", or "migration" (data, not schema):**

1. **Immediately read:** `boranga/components/data_migration/README.md`

2. That file is the **definitive guide** for:

- Adapter architecture

- Schema definitions

- Handler implementation

- Source file conventions

- Verification procedures

**Do NOT proceed with data migration tasks without first consulting that README.**

Testing & Migrations

Tests

Migrations

Project Conventions

Code Organization

URL Patterns

Documentation

Troubleshooting

If APIs aren't working:

1. Check `router.register()` calls in `urls.py`

2. Verify `re_path()` entries for non-ViewSet endpoints

3. Ensure component API module is imported

If startup fails:

1. Verify Ledger service is running and accessible

2. Check all required environment variables (see `README.md`)

3. Ensure `are_migrations_running()` pattern is followed for side effects

If frontend isn't building:

1. Check Node version compatibility

2. Run `npm install` in `frontend/boranga`

3. Verify Vite configuration in `frontend/boranga/vite.config.js`

Getting Help

If you need clarification on:

Ask for expansion on that specific area, and provide relevant code context from the files mentioned above.