# yousefbilal/banner-sched-finder architecture

> Architecture diagram of the GitHub repository yousefbilal/banner-sched-finder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yousefbilal/banner-sched-finder
- Repository: https://github.com/yousefbilal/banner-sched-finder

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Client Subgraph
    subgraph "Frontend Client"
        direction TB
        Browser["Client Browser (Static & HTML)"]:::frontend
        Static["Static Assets"]:::frontend
        Templates["HTML Templates"]:::frontend
    end

    %% Backend Server Subgraph
    subgraph "Backend Server"
        direction TB
        Flask["Flask Server (app.py, course.py, utils.py)"]:::backend
        subgraph "Flask Server Code"
            direction TB
            appFlask["app.py"]:::backendDetail
            course["course.py"]:::backendDetail
            utils["utils.py"]:::backendDetail
        end
        Flask --- appFlask
        Flask --- course
        Flask --- utils
    end

    %% Deployment and Infrastructure Subgraph
    subgraph "Deployment and Infrastructure"
        direction TB
        Dockerfile["Dockerfile"]:::deployment
        ComposeDev["docker-compose.dev.yml"]:::deployment
        ComposeProd["docker-compose.prod.yml"]:::deployment
        GithubWorkflow["CI/CD Workflow"]:::deployment
        DockerContainer["Docker Container (Deploys Frontend & Backend)"]:::deployment
    end

    %% Other Components
    Database["MongoDB Atlas (Data Persistence)"]:::database
    Scraper["External Scraper & Cron Job (Data Ingestion)"]:::external

    %% Relationships
    Browser -->|"HTTPrequests"| Flask
    Flask -->|"HTTPstreaming"| Browser
    Flask -->|"DataAccess"| Database
    Scraper -->|"DataIngestion"| Database

    %% Frontend internal flow
    Static --> Browser
    Templates --> Browser

    %% Deployment relationships
    DockerContainer --> Browser
    DockerContainer --> Flask
    Dockerfile --> DockerContainer
    ComposeDev --> DockerContainer
    ComposeProd --> DockerContainer
    GithubWorkflow --> DockerContainer

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef backendDetail fill:#a1e1a1,stroke:#0f5132,stroke-width:2px;
    classDef database fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef deployment fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;

    %% Click Events
    click Static "https://github.com/yousefbilal/banner-sched-finder/tree/main/static/"
    click Templates "https://github.com/yousefbilal/banner-sched-finder/blob/main/templates/index.html"
    click appFlask "https://github.com/yousefbilal/banner-sched-finder/blob/main/app.py"
    click course "https://github.com/yousefbilal/banner-sched-finder/blob/main/course.py"
    click utils "https://github.com/yousefbilal/banner-sched-finder/blob/main/utils.py"
    click Dockerfile "https://github.com/yousefbilal/banner-sched-finder/tree/main/Dockerfile"
    click ComposeDev "https://github.com/yousefbilal/banner-sched-finder/blob/main/docker-compose.dev.yml"
    click ComposeProd "https://github.com/yousefbilal/banner-sched-finder/blob/main/docker-compose.prod.yml"
    click GithubWorkflow "https://github.com/yousefbilal/banner-sched-finder/blob/main/.github/workflows/docker-publish.yml"
```
