Volunteer Hours Management API

A coursework-ready backend API for managing volunteers, events, shifts, work logs, CSV imports, and worked-hours analytics.

This project is designed for event organisers who need a structured backend system to:

• manage volunteers and events
• create shifts for events
• record volunteer work logs
• calculate official worked hours
• import existing CSV data
• view analytics such as leaderboard, awards, and volunteer summaries

Tech stack

• Python + FastAPI
• SQLAlchemy ORM
• Alembic migrations
• Pydantic schemas
• SQLite (local development)
• JWT authentication
• Pytest

Features

Authentication and roles

• User registration

• User login

• Current user endpoint

• JWT-based authentication

• Role support:

  • admin
  • organiser

Volunteer management

• Create volunteer
• List volunteers
• Get volunteer by ID
• Update volunteer
• Delete volunteer
• Volunteer total hours summary

Event management

• Create event
• List events
• Get event by ID
• Update event
• Delete event
• Event total hours summary

Shift management

• Create shifts for events
• List shifts for an event
• Get shift by ID
• Update shift
• Delete shift

Work logs

• Create work logs

• Get work log by ID

• Update work log

• Delete work log

• Automatic worked_minutes calculation based on:

  • shift start/end
  • volunteer check-in/check-out

• Validation for invalid work log times

• Duplicate work log prevention for the same volunteer and shift

CSV import

Admin-only CSV import endpoints:

• POST /imports/volunteers
• POST /imports/events
• POST /imports/attendance

Analytics and stats

• GET /analytics/leaderboard
• GET /analytics/awards
• GET /analytics/volunteers/{volunteer_id}/summary
• GET /stats

Homepage and accessibility

• Custom homepage at /
• Accessibility toolbar with text size controls (small / medium / large)
• High-contrast greyscale colour-blind mode toggle (WCAG 2.1 Level AAA, 21:1 contrast ratio)
• Admin statistics dashboard at /dashboard — admins paste their JWT token to view live system totals

Worked-hours logic

Worked time is calculated from checked_in_at and checked_out_at, capped to the shift boundaries.

The logic is:

• effective_start = max(checked_in_at, shift.start_time)
• effective_end = min(checked_out_at, shift.end_time)
• worked_minutes = max(0, effective_end - effective_start)

This prevents over-counting outside the planned shift window.

Project structure

app/
  core/
  db/
  models/
  routers/
  schemas/
  services/
  utils/
  main.py
alembic/
docs/
tests/

Setup

1. Clone the repository

git clone https://github.com/Raed-7/volunteer-hours-API-cw1.git
cd volunteer-hours-API-cw1

2. Create and activate a virtual environment

python -m venv .venv

On Windows PowerShell:

.venv\Scripts\Activate.ps1

3. Install dependencies

pip install -r requirements.txt

4. Create your local environment file

copy .env.example .env

5. Set Python path for the current shell

On Windows PowerShell:

$env:PYTHONPATH = (Get-Location).Path

6. Run database migrations

alembic upgrade head

7. Start the API server

uvicorn app.main:app --reload

8. Open the project

• Homepage: https://volunteer-hours-api-cw1.onrender.com/
• API Docs: https://volunteer-hours-api-cw1.onrender.com/docs
• Admin Dashboard: https://volunteer-hours-api-cw1.onrender.com/dashboard

Running tests

pytest -q

Continuous Integration (CI)

GitHub Actions is configured to run the test suite automatically on pushes to main.

Importing CSV data

The API supports CSV uploads through admin-only endpoints.

Use Swagger at /docs, authorize as an admin, then upload:

• volunteers_import_template_en.csv
• events_import_template_en.csv
• attendance_import_template_en.csv

Available endpoints:

• POST /imports/volunteers
• POST /imports/events
• POST /imports/attendance

Main route groups

• /
• /auth
• /volunteers
• /events
• /shifts
• /work-logs
• /imports
• /analytics
• /stats
• /health

Field naming note

• Auth registration currently uses full_name
• Volunteer payload currently uses name

This difference is kept for compatibility with the current implementation.

Documentation

• API Documentation (Markdown)
• API Documentation (PDF)

Datasets

The repository includes example datasets used for testing and demonstration:

• the datasets were based on previous volunteering records
• permission was obtained to use them
• the API replaces the manual Excel-based process by importing, storing, and analysing the records automatically.
• Real data:

• datasets/volunteers.csv
• datasets/events.csv
• datasets/attendance.csv These datasets were prepared from previous volunteering records and are used to demonstrate the CSV import and analytics workflow.

• Template/example files:

• volunteers_import_template_en.csv
• events_import_template_en.csv
• attendance_import_template_en.csv

Live deployment

The API is deployed and accessible at:

• Homepage: https://volunteer-hours-api-cw1.onrender.com/
• API Docs: https://volunteer-hours-api-cw1.onrender.com/docs
• Admin Dashboard: https://volunteer-hours-api-cw1.onrender.com/dashboard
• Health Check: https://volunteer-hours-api-cw1.onrender.com/health

Notes

• The base URL / now provides a homepage for the project
• The main interactive API interface is available at /docs
• Import endpoints are admin-protected
• Analytics results are most useful after importing volunteer, event, and attendance data

Deployment

The project is deployed on Render using native ASGI (no WSGI wrapper needed).

• Runtime: Python 3.11.9
• Build command: pip install -r requirements.txt && alembic upgrade head
• Start command: uvicorn app.main:app --host 0.0.0.0 --port $PORT
• Database: SQLite (ephemeral on Render free tier — re-import datasets after each deploy)

Final note

This project was prepared for coursework submission and oral demonstration.