Skip to content

System Architecture

This page provides an overview of the architecture powering AggieSeek, including the frontend, backend services, infrastructure, and external integrations.

Overview Diagram

System Diagram

The full system flow from user request to notification.

🧱 1. Core Components

🖥️ Frontend (Next.js)

  • Built with Next.js and TailwindCSS
  • Uses Next.js API routes for server-side actions
  • Served behind an NGINX reverse proxy
  • Dockerized and deployed to a Hetzner VPS
  • Auth via Google (NextAuth) and Discord OAuth2

🧠 Backend Services

📦 Tracker Service (tracker.py)

  • Runs every minute
  • Fetches course availability from Howdy
  • Compares with local SQLite3 cache
  • Sends alerts via Twilio and Discord Webhooks

📦 Updater Service (updater.py)

  • Runs every 10 minutes
  • Pulls all course data from Howdy
  • Processes using pandas
  • Updates PostgreSQL (Amazon RDS) with upserts

🗃️ 2. Databases

🐘 PostgreSQL (Amazon RDS)

  • Stores user accounts, tracked sections, and public course data
  • Queried by Next.js API routes and updater

🧩 SQLite3 (Local)

  • Maintains previous course states for diff comparisons
  • Used only by tracker.py

🔐 3. Authentication

  • Google OAuth via NextAuth.js
  • Discord OAuth via dedicated route to store Discord IDs
  • Protected documentation (MkDocs) served via Flask + Google OAuth or Cloudflare Access

📦 4. Deployment & Infrastructure

Component Hosted On Containerized
Next.js App Hetzner VPS ✅ Docker
NGINX Reverse Proxy Hetzner VPS ✅ Docker
Python Services Hetzner VPS ✅ Docker
PostgreSQL DB Amazon RDS ❌
Flask Docs Hetzner VPS (optional) ✅ Docker
  • DNS via Cloudflare
  • SSL/TLS terminated at Cloudflare or NGINX
  • Cloudflare Access restricts documentation access

🌐 5. External Integrations

  • Howdy API: Primary source of course and seat data
  • Twilio API: Sends SMS notifications
  • Discord Webhooks & OAuth: Sends pings, links accounts

🧭 6. Request Flow Summary

  1. User requests aggieseek.net
  2. Cloudflare proxies to NGINX
  3. NGINX serves built Next.js app
  4. Next.js:
  5. Renders UI
  6. Calls API routes
  7. API routes query PostgreSQL
  8. Tracker service:
  9. Pulls latest course data from Howdy
  10. Compares with SQLite3
  11. Notifies via Twilio/Discord
  12. Updater service:
  13. Refreshes PostgreSQL with new Howdy data

📌 Future Improvements

  • Add caching for public course views
  • Split services into independent containers for autoscaling
  • Deploy docs to Cloudflare Pages + Access