Balancer

Balancer is a website of digital tools designed to help prescribers choose the most suitable medications for patients with bipolar disorder, helping them shorten their journey to stability and well-being

Usage

You can view the current build of the website here: https://balancerproject.org/

Contributing

Join the Balancer community

Balancer is a Code for Philly project

Join the Code for Philly Slack and introduce yourself in the #balancer channel

The project kanban board is on GitHub here

Code for Philly Code of Conduct

The Code for Philly Code of Conduct is here

Setting up a development environment

Get the code using git by either forking or cloning CodeForPhilly/balancer-main

1. Copy the example environment file:

   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
2. Postman: Ask to get invited to the Balancer Postman team balancer_dev
3. npm: In the terminal run 1) 'cd frontend' 2) 'npm install' 3) 'cd ..'

Running Balancer for development

Start the Postgres, Django REST, and React services by starting Docker Desktop and running docker compose up --build

Postgres

The application supports connecting to PostgreSQL databases via:

1. CloudNativePG - Kubernetes-managed PostgreSQL cluster (for production/sandbox)
2. AWS RDS - External PostgreSQL database (AWS managed)
3. Local Docker Compose - For local development

See Database Connection Documentation for detailed configuration.

Local Development:

• Download a sample of papers to upload from 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
  • The Username and Password are the Postgres server environment variables in the Docker Compose file
• You can use the below code snippet to query the database from a Jupyter notebook:

from sqlalchemy import create_engine
import pandas as pd

engine = create_engine("postgresql+psycopg2://balancer:balancer@localhost:5433/balancer_dev")

query = "SELECT * FROM api_embeddings;"

df = pd.read_sql(query, engine)

Django REST

• The email and password are set in server/api/management/commands/createsu.py

API Documentation

Interactive API docs are auto-generated using drf-spectacular and available at:

• Swagger UI: http://localhost:8000/api/docs/ — interactive explorer with "Try it out" functionality
• ReDoc: http://localhost:8000/api/redoc/ — clean, readable reference docs
• Raw schema: http://localhost:8000/api/schema/ — OpenAPI 3.0 JSON/YAML

Testing authenticated endpoints

Most endpoints require JWT authentication. To test them in Swagger UI:

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

The Balancer website is a Postgres, Django REST, and React project. The source code layout is:

License

Balancer is licensed under the AGPL-3.0 license