# bdlg-2023-server

This repository hosts an API that helps volunteer managers plan festival
activities on a schedule, associate volunteers to time slots, and send SMS
reminders during the event. Volunteer/slot data can also be bootstrapped
from a Google Sheet import.

## Core concepts

- **Organization** — the top-level tenant. Every user belongs to zero or
  more organizations (multi-org membership is supported). Every project
  belongs to exactly one organization, which defines who can access it.
- **Global roles** — `user` (default) or `super_admin`. Only `super_admin`
  can create/edit organizations and manage organization membership.
- **Organization roles** (per user, per organization):
    - `org_admin` — full control over the organization's projects and can
      change member roles within their own organization.
    - `respo_benevole` — manages volunteer allocation across the whole
      project: slots, templates, volunteers, groups, and SMS.
    - `respo_commission` — read access to the whole project plan; write
      access limited to templates/slots belonging to the commission(s) they
      are a member of. Cannot manage volunteers, groups, or SMS directly.
- **Commission** (Pôle) — represents a team/area within a project (e.g.
  "Bar", "Accueil"). A commission's contact info is derived from its
  members' own profile (`name` + `phone_number`) rather than stored as
  free text — see `SlotTemplate.responsible_override` for the manual
  exception case.
- **Volunteer group** — a saved, searchable set of volunteers within a
  project, usable for bulk slot assignment and group SMS.

## Getting started

For running the application

```bash
git clone ...
cd ...
python -m venv venv
venv/scripts/activate
poetry install
```

Note, be sure to use python3.11 with this application

* Copy .env.example to .env and edit it to configure your setup

```bash
init.sh
uvicorn app.main:app --reload
```

### Bootstrapping the first organization / super_admin

New databases start with no organizations and no `super_admin`. After
running migrations, promote the first user manually (there is currently
no API endpoint for this, by design — it's a one-time operational step):

```sql
UPDATE user_model
SET global_role = 'SUPER_ADMIN'
WHERE email = '<you>';
```

From there, that user can create organizations and add members via the
`/organizations` endpoints.

## Debug

```bash
python -m app.debug
```

Run tests

```bash
pytest
pytest app\test\test_volunteer.py
```

Run coverage tests

```bash
coverage run -m pytest
coverage html
```

## Database migrations

```bash
# create migration
alembic revision --autogenerate -m "migration_name"
# apply all migrations
alembic upgrade head
```

Autogenerated migrations are a starting point, not a final draft —
review them by hand, especially for:

- new `NOT NULL` columns on tables that may already have data (add
  nullable, backfill, then tighten in the same migration)
- new Postgres ENUM types referenced outside a `create_table` block
  (need an explicit `create_type=False` + manual `CREATE TYPE`/`DROP TYPE`)
- FK `ondelete` behavior vs. the SQLAlchemy relationship's own cascade
  config (see `passive_deletes=True` on `Organization.projects` — without
  it, `session.delete(org)` tries to null out `Project.organization_id`
  in Python before the DB's `ON DELETE CASCADE` ever runs, which fails
  since that column is `NOT NULL`)

## Update requirements

```bash
poetry lock
poetry export -f requirements.txt --output requirements.txt --without-hashes
poetry export -f requirements.txt --output requirements-dev.txt --without-hashes --with dev
```

## Update frontend API types

```bash
npm run update-schema
```

Regenerate after any backend route or schema change — see the frontend
repo's README for details.

## Credit

FastAPI project generated using https://github.com/rafsaf/minimal-fastapi-postgres-template