AV's RHS Schedule Engine

High-performance RESTful API Engine built in Go for querying high school schedules, classes, teachers, and student records.

Description

RHS Schedule Engine is a high-performance backend built in Go using the Gin web framework and PostgreSQL (Supabase). This is useful for finding students during classes, which RIOT, Yearbook, and Admin all do. Designed to handle complex school scheduling architectures, it processes multi-year student rosters, class schedules, and teacher assignments while delivering low-latency queries with excellent API security and request throttling.

The project has these features:

• JWT & Demo Authentication: Secures endpoints with 24-hour JWT token validation, and a public demo mode (Bearer demo-key).

• Student & Schedule Management: Supports fast paginated lookup of student profiles, grade-based filtering, name searching, and multi-year schedule retrieval.

• Teacher & Class Analytics: Provides specialized lookup for teacher rosters, course catalogs, and teacher period schedule maps.

• Middleware Engine: Includes rate limiting (60 req/min limit per client IP), CORS configuration, and auth management.

• Documentation: Integrated OpenAPI/Swagger UI powered by swaggo/gin-swagger for testing on website directly.

Demo

The demo is built right into the docs website!

As a Demo User

• Go to 3.85.169.88/swagger/index.html
• Click on the button that says "Authorize", and set the value of your apiKey to Bearer demo-key
• Go to any method and expand it
• Click on "Try it out", adjust any of the parameters, and press execute!

Note

The demo-key will return dummy data, and have lower rate limiting!

As a Real User

• Generate your JWT using your login. See test_auth.py for an example.
• Go to 3.85.169.88/swagger/index.html
• Click on the button that says "Authorize", and set the value of your apiKey to Bearer {replace with JWT token}
• Go to any method and expand it
• Click on "Try it out", adjust any of the parameters, and press execute!

Note

The JWT will only be active for 24 hours. Regenerate another one when it expires!

With Python/Coding

• See this file as an example
• Note how the Headers and Params are provided
• You can apply this to any language!

Dependencies

• Make sure you have go installed (v1.26+ recommended)!
• PostgreSQL or Supabase database instance (or run in built-in Demo Mode without a database connection)
• swag CLI tool if re-generating OpenAPI documentation (go install github.com/swaggo/swag/cmd/swag@latest)
• Docker if you prefer to run inside an Alpine containerized environment

Installing

• Clone the repository from GitHub:
  • git clone https://github.com/AV-01/RHS-Schedule-Engine.git
  • cd RHS-Schedule-Engine
• Download dependencies:
  • go mod download
• Create a .env file in the root directory:
  • SUPABASE_DB_URL=postgres://user:password@host:port/dbname
  • JWT_SECRET=your_secret_key_here

Executing program

If you are running locally with Go

• Make sure you are in the project root directory RHS-Schedule-Engine\
• Open terminal and run: go run main.go
• Open your browser and navigate to http://localhost:8080/swagger/index.html
• Enjoy the magic!

If you are using Docker

• Build the container: docker build -t rhs-schedule-engine .
• Run the container: docker run -p 8080:8080 rhs-schedule-engine
• Access the API at http://localhost:8080/api/v1

Warning

Do not commit real SUPABASE_DB_URL strings or JWT_SECRET keys to public repositories! Ensure production secrets are properly stored in environment variables.

Help

Open an issue if you need help!

Version History

• 1.2.0
• Fixed some bugs
• 1.1.0
• Added JWT authentication & login endpoint
• Added rate limiting middleware (60 requests/min per IP)
• Added login audit logger middleware
• Added Swagger API documentation via gin-swagger
• 1.0.0
• Added student, teacher, and class schedule API endpoints
• Integrated PostgreSQL / Supabase backend connection
• Added data parsing and cleaning scripts for multi-year schedule data
• 0.1.0
• Initial Release

License

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

Authors

Made with ❤️ by AV