A full-stack web application for managing swim meet data — meets, sessions, athletes, teams, and results.
Built with Flask, React (TypeScript), PostgreSQL, and Docker.

---

Quick Start

Prerequisites

• Docker Desktop installed and running.

Setup Instructions

1. Clone the repository:

   git clone https://github.com/SpeedoMan25/Halcyon.git
   cd Halcyon

2. Configure environment:

   cp .env.example .env

   Customize .env with your own secrets for production use.

3. Start the stack:

   docker-compose up --build

4. Access the app:
   • Frontend: http://localhost:5173
   • Backend API: http://localhost:5000

---

Project Structure

Halcyon/
├── backend/                 # Flask API
│   ├── app/
│   │   ├── models/          # Data models (raw SQL)
│   │   ├── routes/          # API endpoints
│   │   ├── schemas/         # Request/response validation
│   │   ├── services/        # Business logic
│   │   └── utils/           # Helpers & security
│   ├── database/
│   │   └── init.sql         # Schema & seed data
│   ├── docs/                # API & DB documentation
│   └── tests/               # pytest suite
├── frontend/                # React (Vite) + TypeScript
│   ├── src/
│   │   ├── api/             # Backend API client
│   │   ├── components/      # Reusable UI components
│   │   └── pages/           # Application pages
│   └── public/              # Static assets
├── assets/                  # Branding & logos
├── scripts/                 # Local dev helper scripts
├── docker-compose.yml       # Full-stack orchestration
└── .github/workflows/       # CI/CD pipelines

---

Key Features

• Professional UI — Premium dark-themed design with smooth transitions and glassmorphism.
• Meet Management — Comprehensive management of swim meets, sessions, and events.
• Entity Tracking — Full CRUD for Teams, Swimmers, Coaches, Officials, and Pools.
• Results & Timing — Advanced results tracking with support for multiple timing events.
• Authentication — Secure JWT-based registration and login system.
• Import System — Bulk data import from structured files.
• Global Search — Search across all entities from a single search bar.
• API Documentation — Auto-generated Swagger UI and Redoc via APIFlask.

---

API

Once the stack is running, interactive API docs are available at:

• Swagger UI: http://localhost:5000/docs
• Redoc: http://localhost:5000/redoc

Module	Description
Auth	User registration, login, and profile management
Teams	Swimming organizations and clubs
Swimmers	Athlete profiles and registration details
Coaches	Coaching staff and team assignments
Officials	Meet official roles and contact information
Pools	Pool facilities and lane configurations
Events	Swim event definitions (distance, stroke, gender)
Results	Race times, disqualifications, and timing data
Standards	Time standards and qualifying criteria

See backend/docs/API.md for full details.

---

Testing

The backend includes a comprehensive pytest suite:

# Start the test database
docker-compose up -d db-test

# Run tests from the backend container
docker-compose exec backend pytest

See backend/docs/DATABASE.md for the database architecture.

---

CI/CD

GitHub Actions workflows run on every push and PR to main:

Workflow	What it does
Docker Build	Builds backend & frontend Docker images
Backend Tests	Runs the pytest suite against a PostgreSQL service
Backend Quality	Ruff linting/formatting + Mypy type checking
Frontend CI	ESLint + TypeScript type check + Vite build

---

Local Development (without Docker)

PowerShell helper scripts are provided for running outside of Docker:

# One-time setup (creates venv, installs dependencies)
.\scripts\setup_local.ps1

# Start backend & frontend in separate windows
.\scripts\start_local.ps1

Note: You'll still need a PostgreSQL instance running locally or via Docker.

---

Database Reset

The database is automatically initialized with init.sql on first run. To reset:

docker-compose down -v
docker-compose up --build

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License — see the LICENSE file for details.