Sessions Management System

A comprehensive session management platform for organizing and managing youth programs, classes, and activities. The system provides both public-facing session discovery and caregiver signup capabilities, along with powerful administrative tools for staff.

🌟 Features

Public Features

Session Discovery: Browse available sessions by region with search and filtering
Detailed Information: View session schedules, locations, age requirements, and capacity
Calendar Export: Download session calendars in .ics format for personal calendars

Caregiver Portal

Magic Link Authentication: Secure, passwordless login via email
Child Management: Register and manage multiple children
Session Signups: Enroll children in sessions with automatic age eligibility checking
Waitlist Management: Automatic waitlist placement when sessions are full or age-ineligible
Session History: Track enrollments and attendance

Admin Portal

Google OAuth Authentication: Secure staff login with Google accounts
Session Management: Create and manage term-based and special sessions
Block/Term Configuration: Set up school terms and special event blocks
Location Management: Configure venues with maps and details
Attendance Tracking: Take attendance with detailed roll calls
Student Management: View student profiles, medical info, and signup history
Exclusion Dates: Manage school holidays and closure dates
Calendar Overview: Visual calendar of all session occurrences
Bulk Communications: Send emails to session participants

🏗️ Architecture

The system consists of three main components:

Component	Tech Stack	Purpose
Backend API	Python 3.13+, Litestar, PostgreSQL	RESTful API with business logic
Admin Portal	React 19, TypeScript, Tailwind CSS	Staff administration interface
Frontend	Astro 5, TypeScript, Tailwind CSS	Public session discovery and caregiver portal

🚀 Quick Start

Prerequisites

Docker & Docker Compose - For containerized development and deployment
Node.js 24+ & pnpm 10+ - For frontend/admin portal development
Python 3.13+ & uv - For backend development
PostgreSQL 16+ - For local development (optional if using Docker)

Quick Setup with Docker

git clone https://github.com/Tuhura-Tech/sessions.git
cd sessions
docker compose up -d

Access the application:

Local Development Setup

Backend

cd backend
cp .env.example .env
# Edit .env with your configuration
uv sync
uv run alembic upgrade head
uv run litestar run --reload

The backend will be available at http://localhost:8000

Admin Portal

cd admin_portal
cp .env.example .env
pnpm install
pnpm run dev

Access at http://localhost:5173

Frontend

cd frontend
pnpm install
pnpm run dev

Access at http://localhost:4321

🛠️ Development

Project Structure

sessions/
├── backend/              # Litestar REST API
│   ├── app/             # Application code
│   ├── tests/           # Unit and integration tests
│   └── alembic/         # Database migrations
├── admin_portal/         # React admin dashboard
│   ├── src/             # React components and logic
│   └── tests/           # Playwright E2E tests
├── frontend/             # Astro public site
│   ├── src/             # Astro components and pages
│   └── tests/           # Playwright E2E tests
└── docker-compose.yml   # Local development environment

Code Style & Linting

Backend:

cd backend
uv run ruff check .        # Lint with Ruff
uv run ruff format .       # Format with Ruff

Frontend & Admin Portal:

cd frontend  # or admin_portal
pnpm run lint:fix          # Fix with Biome
pnpm run format            # Format with Prettier

Running Development Servers

All three services support hot reload:

# Terminal 1: Backend
cd backend && uv run litestar run --reload

# Terminal 2: Admin Portal
cd admin_portal && pnpm run dev

# Terminal 3: Frontend
cd frontend && pnpm run dev

🧪 Testing

Backend Tests

cd backend
uv run pytest                              # Run all tests
uv run pytest --cov=app --cov-report=html # With coverage report
uv run pytest -v                          # Verbose output

Frontend E2E Tests

cd admin_portal
pnpm run test                     # Run Playwright tests
pnpm run test:ui                  # Interactive test UI
pnpm run test:headed              # Run with browser visible
pnpm run test:debug               # Debug mode

cd frontend
pnpm run test:e2e                 # Run E2E tests
pnpm run test:e2e:ui              # Interactive test UI

Type Checking

# Frontend
cd frontend && pnpm run check

# Admin Portal
cd admin_portal && tsc --noEmit

🚢 Deployment

Docker Images

Pre-built Docker images are automatically published to GitHub Container Registry:

ghcr.io/Tuhura-Tech/sessions/backend:latest
ghcr.io/Tuhura-Tech/sessions/admin-portal:latest
ghcr.io/Tuhura-Tech/sessions/frontend:latest

Images are built for both linux/amd64 and linux/arm64 architectures.

Environment Variables

Backend

Create backend/.env with:

DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/sessions
SECRET_KEY=your-secret-key-here
LITESTAR_DEBUG=false

# OAuth
GOOGLE_CLIENT_ID=your-google-oauth-client-id
GOOGLE_CLIENT_SECRET=your-google-oauth-secret
GOOGLE_REDIRECT_URI=http://localhost:8000/api/v1/admin-auth/callback

# Email (optional)
SMTP_HOST=smtp.example.com
SMTP_PORT=587

See backend/.env.example for all available options.

Frontend & Admin Portal

# admin_portal/.env
VITE_API_URL=http://localhost:8000/api/v1

# frontend/.env
PUBLIC_API_URL=http://localhost:8000/api/v1

Database Management & Migrations

The project includes comprehensive database management scripts in the scripts/ directory. See scripts/README.md for complete documentation.

Quick Start

# Initialize new database with sample data
python scripts/db_init.py --seed

# Reset database (development)
./scripts/db_reset.sh --seed

# Create migration
./scripts/db_migrate.sh create "Add new field"

# Apply migrations
./scripts/db_migrate.sh up

Migration Scripts

All database scripts are located in /scripts:

Script	Purpose	Quick Usage
`db_init.py`	Initialize new database	`python scripts/db_init.py --seed`
`db_reset.sh`	Reset to clean state	`./scripts/db_reset.sh --seed`
`db_migrate.sh`	Migration management	`./scripts/db_migrate.sh up`
`migrate_legacy_data.py`	Import legacy data	`python scripts/migrate_legacy_data.py backup.sql`

Common Workflows

First-time setup:

docker compose up -d
python scripts/db_init.py --seed

Create & apply migration:

./scripts/db_migrate.sh create "Add user preferences"
# Review generated file in backend/app/db/migrations/versions/
./scripts/db_migrate.sh up

Reset development database:

./scripts/db_reset.sh --seed

Import legacy data:

python scripts/migrate_legacy_data.py backup.sql

Check migration status:

./scripts/db_migrate.sh status
./scripts/db_migrate.sh history

Migration Best Practices

Always use migrations for schema changes - Never manually alter the database
Test migrations both ways - Apply and rollback to verify
Review generated migrations - Check the code in backend/app/db/migrations/versions/
Keep migrations small - One logical change per migration
Backup before production migrations - Always have a rollback plan

For detailed documentation, troubleshooting, and advanced usage, see scripts/README.md.

📚 API Documentation

The backend API is fully documented with OpenAPI/Swagger:

Development: http://localhost:8000/docs
Production: https://your-domain.com/docs

Key Endpoints

GET /api/v1/sessions - List sessions
POST /api/v1/sessions - Create session (admin only)
GET /api/v1/locations - List locations
POST /api/v1/signups - Create enrollment
POST /api/v1/admin/login - Admin authentication

🏛️ Database Schema

Core Entities

Sessions - Class/program definitions with capacity and age requirements
SessionBlocks - Time periods (terms, special events)
SessionOccurrences - Individual class meetings
Signups - Student enrollments with status tracking
Students - Student profiles with personal information
Caregivers - Parent/guardian accounts
Staff - Admin users with role-based access
Locations - Venue information with coordinates
ExclusionDates - Holidays and facility closures
Attendance - Attendance records for each occurrence

Schema Management

Migrations are managed with Alembic and tracked in backend/app/db/migrations/versions/.

View current schema:

./scripts/db_migrate.sh status
./scripts/db_migrate.sh history

Modify schema:

# 1. Update models in backend/app/db/models.py
# 2. Generate migration
./scripts/db_migrate.sh create "Describe your change"
# 3. Review migration file
# 4. Apply migration
./scripts/db_migrate.sh up

For complete database management documentation, see scripts/README.md.

🤖 AI-Powered Development

This project uses GitHub Copilot for development assistance. See AGENTS.md for information about AI agents and automated development workflows.

🤝 Contributing

See CONTRIBUTING.md for:

Development guidelines
Code style standards
PR process
Commit message conventions

📄 License

This project is licensed under the GNU Affero General Public License v3 (AGPL-3.0) - see the LICENSE file for details.

🔒 Security

For security concerns, please email security@tuhura.co.nz instead of using the issue tracker.

See SECURITY.md for our full security policy and disclosure process.

🙏 Acknowledgments

Built with modern, industry-standard technologies:

Litestar - Modern Python web framework
React - UI library
Astro - Web framework
PostgreSQL - Relational database
Tailwind CSS - Utility-first CSS
Docker - Container platform
GitHub Actions - CI/CD

📧 Support

For questions and support:

Open an issue on GitHub Issues
Check Discussions for Q&A
Email: contact@tuhuratech.org.nz

Made with ❤️ by the Tūhura Tech team

Name		Name	Last commit message	Last commit date
Latest commit History 239 Commits
.github		.github
admin_portal		admin_portal
backend		backend
docs		docs
frontend		frontend
.env.example		.env.example
.envrc		.envrc
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
renovate.json		renovate.json
shell.nix		shell.nix

License

Tuhura-Tech/sessions

Folders and files

Latest commit

History

Repository files navigation

Sessions Management System

🌟 Features

Public Features

Caregiver Portal

Admin Portal

🏗️ Architecture

📋 Table of Contents

🚀 Quick Start

Prerequisites

Quick Setup with Docker

Local Development Setup

Backend

Admin Portal

Frontend

🛠️ Development

Project Structure

Code Style & Linting

Running Development Servers

🧪 Testing

Backend Tests

Frontend E2E Tests

Type Checking

🚢 Deployment

Docker Images

Environment Variables

Backend

Frontend & Admin Portal

Database Management & Migrations

Quick Start

Migration Scripts

Common Workflows

Migration Best Practices

📚 API Documentation

Key Endpoints

🏛️ Database Schema

Core Entities

Schema Management

🤖 AI-Powered Development

🤝 Contributing

📄 License

🔒 Security

🙏 Acknowledgments

📧 Support

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages