Merge branch 'develop' into 441-embedding-models

Author: sahilds1

.github/workflows/containers-publish.yml

@@ -26,12 +26,17 @@ jobs:
       - name: Compute Docker container image addresses
         run: |
           DOCKER_REPOSITORY="ghcr.io/${GITHUB_REPOSITORY,,}"
+          git fetch --tags --force
           
           if [[ "${{ github.event_name }}" == "release" ]]; then
-            DOCKER_TAG="${GITHUB_REF:11}"
+            TAG="${GITHUB_REF#refs/tags/}"
+            DOCKER_TAG="${TAG#v}"
           else
-            SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
-            DOCKER_TAG="dev-${SHORT_SHA}"
+            # Pre-release for develop
+            BASE_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0")
+            VERSION="${BASE_TAG#v}"
+            TIMESTAMP=$(date +%Y%m%d%H%M%S)
+            DOCKER_TAG="${VERSION}-dev.${TIMESTAMP}"
           fi
 
           echo "DOCKER_REPOSITORY=${DOCKER_REPOSITORY}" >> $GITHUB_ENV
@@ -52,6 +57,7 @@ jobs:
               --file Dockerfile.prod \
               --tag "${DOCKER_REPOSITORY}/app:latest" \
               --tag "${DOCKER_REPOSITORY}/app:${DOCKER_TAG}" \
+              --build-arg VERSION="${DOCKER_TAG}" \
               .
 
       - name: "Push Docker container image app:latest"

.github/workflows/deploy-downstream.yml

@@ -0,0 +1,35 @@
+name: "Frontend: Lint and Build"
+
+on:
+  push:
+    branches: [develop]
+  pull_request:
+    branches: [develop]
+
+jobs:
+  frontend:
+    name: Lint and Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+          cache: "npm"
+          cache-dependency-path: frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Lint
+        run: npm run lint
+        continue-on-error: true
+
+      - name: Build
+        run: npm run build
+        continue-on-error: true

.github/workflows/frontend-ci.yml

@@ -147,6 +147,16 @@ Each module contains:
 - Auth endpoints via Djoser: `/auth/`
 - JWT token lifetime: 60 minutes (access), 1 day (refresh)
 
+#### API Documentation
+- Auto-generated using **drf-spectacular** (OpenAPI 3.0)
+- **Swagger UI**: `http://localhost:8000/api/docs/` — interactive API explorer
+- **ReDoc**: `http://localhost:8000/api/redoc/` — readable reference docs
+- **Raw schema**: `http://localhost:8000/api/schema/`
+- Configuration in `SPECTACULAR_SETTINGS` in `settings.py`
+- Views use `@extend_schema` decorators and `serializer_class` attributes for schema generation
+- JWT auth is configured in the schema — use `JWT <token>` (not `Bearer`) in Swagger UI's Authorize dialog
+- To document a new endpoint: add `serializer_class` to the view if it has one, or add `@extend_schema` with `inline_serializer` for views returning raw dicts
+
 #### Key Data Models
 - **Medication** (`api.views.listMeds.models`) - Medication catalog with benefits/risks
 - **MedRule** (`api.models.model_medRule`) - Include/Exclude rules for medications based on patient history
@@ -278,28 +288,6 @@ docker compose exec backend python manage.py test
 ### Frontend Tests
 No test framework currently configured. Consider adding Jest/Vitest for future testing.
 
-## Deployment
-
-### Local Kubernetes (using Devbox)
-```bash
-# Install Devbox first: https://www.jetify.com/devbox
-
-# Add balancertestsite.com to /etc/hosts
-sudo sh -c 'echo "127.0.0.1      balancertestsite.com" >> /etc/hosts'
-
-# Deploy to local k8s cluster
-devbox shell
-devbox create:cluster
-devbox run deploy:balancer
-
-# Access at https://balancertestsite.com:30219/
-```
-
-### Production
-- Manifests: `deploy/manifests/balancer/`
-- ConfigMap: `deploy/manifests/balancer/base/configmap.yml`
-- Secrets: `deploy/manifests/balancer/base/secret.template.yaml`
-
 ## Key Files Reference
 
 - `server/balancer_backend/settings.py` - Django configuration (auth, database, CORS)

CLAUDE.md

@@ -21,6 +21,10 @@ RUN npm run build
 # Stage 2: Build Backend
 FROM python:3.11.4-slim-bullseye
 
+# Receive version argument from build command
+ARG VERSION
+ENV VERSION=${VERSION}
+
 # Set work directory
 WORKDIR /usr/src/app
 

Dockerfile.prod

@@ -5,7 +5,7 @@ for patients with bipolar disorder, helping them shorten their journey to stabil
 
 ## Usage
 
-You can view the current build of the website here: [https://balancertestsite.com](https://balancertestsite.com/)
+You can view the current build of the website here: [https://balancerproject.org/](https://balancerproject.org/)
 
 ## Contributing 
 
@@ -21,13 +21,17 @@ The project kanban board is [on GitHub here](https://github.com/orgs/CodeForPhil
 
 The Code for Philly Code of Conduct is [here](https://codeforphilly.org/pages/code_of_conduct/) 
 
-### Setting up a development environment   
+### Setting up a development environment
 
 Get the code using git by either forking or cloning `CodeForPhilly/balancer-main`
 
-Tools used to run Balancer:
-1. `OpenAI API`: Ask for an API key and add it to `config/env/env.dev`
-2. `Anthropic API`: Ask for an API key and add it to `config/env/env.dev`
+1. Copy the example environment file:
+   ```bash
+   cp config/env/dev.env.example config/env/dev.env
+   ```
+2. (Optional) Add your API keys to `config/env/dev.env`:
+   - `OpenAI API`
+   - `Anthropic API`
 
 Tools used for development:
 1. `Docker`: Install Docker Desktop
@@ -49,7 +53,7 @@ The application supports connecting to PostgreSQL databases via:
 See [Database Connection Documentation](./docs/DATABASE_CONNECTION.md) for detailed configuration.
 
 **Local Development:**
-- Download a sample of papers to upload from [https://balancertestsite.com](https://balancertestsite.com/) 
+- Download a sample of papers to upload from [https://balancerproject.org/](https://balancerproject.org/) 
 - The email and password of `pgAdmin` are specified in `balancer-main/docker-compose.yml`
 - The first time you use `pgAdmin` after building the Docker containers you will need to register the server.
     - The `Host name/address` is the Postgres server service name in the Docker Compose file
@@ -75,39 +79,22 @@ df = pd.read_sql(query, engine)
 docker compose exec backend pytest api/ -v
 ```
 
-## Local Kubernetes Deployment
+## API Documentation
 
-### Prereqs
+Interactive API docs are auto-generated using [drf-spectacular](https://drf-spectacular.readthedocs.io/) and available at:
 
-- Fill the configmap with the [env vars](./deploy/manifests/balancer/base/configmap.yml)
-- Install [Devbox](https://www.jetify.com/devbox)
-- Run the following script with admin privileges:
+- **Swagger UI**: [http://localhost:8000/api/docs/](http://localhost:8000/api/docs/) — interactive explorer with "Try it out" functionality
+- **ReDoc**: [http://localhost:8000/api/redoc/](http://localhost:8000/api/redoc/) — clean, readable reference docs
+- **Raw schema**: [http://localhost:8000/api/schema/](http://localhost:8000/api/schema/) — OpenAPI 3.0 JSON/YAML
 
-```bash
-HOSTNAME="balancertestsite.com"
-LOCAL_IP="127.0.0.1"
+### Testing authenticated endpoints
 
-# Check if the correct line already exists
-if grep -q "^$LOCAL_IP[[:space:]]\+$HOSTNAME" /etc/hosts; then
-  echo "Entry for $HOSTNAME with IP $LOCAL_IP already exists in /etc/hosts"
-else
-  echo "Updating /etc/hosts for $HOSTNAME"
-  sudo sed -i "/[[:space:]]$HOSTNAME/d" /etc/hosts
-  echo "$LOCAL_IP      $HOSTNAME" | sudo tee -a /etc/hosts
-fi
-```
-
-### Steps to reproduce
-
-Inside root dir of balancer
-
-```bash
-devbox shell
-devbox create:cluster
-devbox run deploy:balancer
-```
+Most endpoints require JWT authentication. To test them in Swagger UI:
 
-The website should be available in [https://balancertestsite.com:30219/](https://balancertestsite.com:30219/)
+1. **Get a token**: Find the `POST /auth/jwt/create/` endpoint in Swagger UI, click **Try it out**, enter an authorized `email` and `password`, and click **Execute**. Copy the `access` token from the response.
+2. **Authorize**: Click the **Authorize** button (lock icon) at the top of the page. Enter `JWT <your-access-token>` in the value field. The prefix must be `JWT`, not `Bearer`.
+3. **Test endpoints**: All subsequent requests will include your token. Use **Try it out** on any protected endpoint.
+4. **Token refresh**: Access tokens expire after 60 minutes. Use `POST /auth/jwt/refresh/` with your `refresh` token, or repeat step 1.
 
 ## Architecture