How yousefbilal/banner-sched-finder works
Project Overview
• This is a web application that helps American University of Sharjah students generate all possible conflict-free course schedules based on selected courses. It uses a Flask-based backend paired with a vanilla JavaScript frontend.
• The application uses a backtracking algorithm for schedule generation along with HTTP Streaming so that schedules are sent incrementally, avoiding memory issues with large result sets.
• MongoDB Atlas is used for data persistence (populated via an external scraper running as a cron job—note that the scraper’s source isn’t part of this repo).
• The project includes Docker deployment files (Dockerfile, docker-compose configurations) and GitHub workflows, indicating a cloud-friendly and CI/CD-ready design.
Main Components
• Frontend Client:
• Static assets (JavaScript files, CSS, and HTML templates). These reside in the “static” and “templates” directories.
• How the user interacts via the browser (e.g., selecting courses, viewing schedule visualization).
• Backend Server:
• The Flask application (mostly found in app.py, course.py, and utils.py) that handles HTTP requests, runs the backtracking algorithm, and streams schedule results.
• Fact that the backend uses HTTP streaming to push schedules as they are generated.
• Database:
• External Data Source:
• Although not in the repo code, include an “External Scraper & Cron Job” component. This component, which scrapes information from the university’s banner pages, feeds schedule and course data into MongoDB.
• Deployment and Infrastructure:
• Docker components: The Dockerfile for building the image and the docker-compose configuration files (one for development and one for production).
• Optionally, note that the production Docker setup uses Gunicorn as the WSGI server (as mentioned in the README).
Relationships and Interactions
• Frontend ↔ Backend:
• Backend ↔ Database:
• A connection from the Flask server to MongoDB, representing data fetches or persistence operations.
• External Scraper → Database:
• Deployment Infrastructure:
• That both the frontend and backend are deployed together within Docker containers. Optionally, add a separate boundary to show deployment flow and CI/CD integration (GitHub workflows).
Architectural Patterns and Design Principles
• The design follows a classic full-stack structure where the client, server, and database are independent components.
• There is a clear separation of concerns (frontend presentation separate from backend application logic, which itself isolates schedule generation logic).
• The use of HTTP Streaming is an important architectural decision to handle heavy data transfer (schedules) without overloading the system.
• Dockerization adds a layer of containerization and environment consistency across deployments.