How sharifaminuumar/university-admission-predictor works
1. Project shape
- This is a Flask-based full-stack Python application for predicting Ghanaian university admission eligibility from WASSCE subject/grade inputs.
- The repo is split into a small web UI, a Flask delivery layer, a pure eligibility calculation engine, and a SQLite-backed data store for institutional rules.
2. Request/response boundary
- The browser loads a single-page-style interface from app/templates/index.html.
- User actions are handled in app/static/main.js, which likely submits the student’s grades/program selection asynchronously to Flask routes.
- Flask returns eligibility results back to the UI, which updates the page without a full reload.
3. Web delivery layer
- app/routes.py is the HTTP boundary for the application.
- It is responsible for accepting form/JSON inputs, calling the backend logic, and packaging the response for the frontend.
- main.py and/or run.py serve as the app entrypoints for local execution.
4. Core algorithmic engine
- app/eligibility_engine.py is the main computational subsystem.
- Per the README, it computes optimized WASSCE aggregate scores, including Best-6 style scoring and rule-based eligibility checks.
- This logic is intended to be deterministic and independent of Flask and the database, which makes it the key “business rules” boundary in the system.
5. Domain/data model
- app/models.py defines the SQLAlchemy ORM layer.
- The database appears to store institutional program requirements rather than student records, so the model boundary is centered on admissions criteria and program blueprints.
- The README indicates requirement sets are stored as serialized structured data, not normalized into many relational tables.
6. Persistence layer
- The application uses SQLite, with the live database file at instance/admissions.db.
- SQLAlchemy is the abstraction between the Flask app and the database.
- This layer is used to persist preloaded admission rules and likely to query university/program requirements at runtime.
7. Seed and source data flow
- data/knust.json, data/uds.json, and data/ug.json hold institutional requirement definitions.
- seed_db.py is the ingestion pipeline that loads those JSON files into the SQLite database.
- In architecture terms, the JSON files are the source-of-truth content, while the DB is the runtime store used by the app.
8. Front-end presentation layer
- app/static/style.css provides the visual layout and responsive styling.
- app/static/main.js handles interactive behavior and async submission.
- app/templates/index.html is the main rendering surface, so the UI is server-delivered but client-interactive.
9. Important subsystem boundary: rules vs. infrastructure
- The README emphasizes separation between the algorithmic engine and both the Flask layer and persistence layer.
- That means admission logic should be diagrammed as its own central subsystem, with Flask and SQLAlchemy acting as adapters around it.
- This is the most important architectural boundary in the repo.
10. Data lifecycle
- A typical flow is: institutional JSON data is seeded into SQLite, a user enters grades and program choices in the web UI, Flask receives the request, the engine computes aggregate/eligibility results, and the response is rendered back in the browser.
- No external APIs or third-party services appear to be involved; the system is self-contained around local Flask, local static assets, and local SQLite storage.
11. Technology stack
- Runtime: Python.
- Delivery: Flask.
- ORM/persistence: SQLAlchemy with SQLite.
- UI: server-rendered HTML plus client-side JavaScript and CSS.
- Data format: JSON for admissions rule definitions.
12. What to show in an architecture diagram
- Draw four main boxes: browser UI, Flask routes, eligibility engine, and SQLite/database.
- Add a separate data source box for data/*.json feeding seed_db.py into the database.
- Show the engine as the central compute component, with Flask only orchestrating input/output and the database only supplying program requirements.
Main entry points: routes.py Routes · index.html Admission UI · eligibility_engine.py Eligibility Engine · __init__.py App Bootstrap
Components 14
Browser UI
Server-rendered page with client-side interaction
- Admission UI · Main HTML surface for entering grades and viewing results
app/templates/index.html - Client Logic · Handles interactions and async submission from the page
app/static/main.js - Styles · Presentation and responsive layout styling
app/static/style.css
Flask Delivery
HTTP boundary and app startup
- App Bootstrap · Flask app package initialization and wiring
app/__init__.py - Routes · Request handling and response packaging for eligibility checks
app/routes.py - Main Entry · Local execution entrypoint
main.py - Run Entry · Alternative execution entrypoint
run.py
Eligibility Core
Deterministic admissions scoring and rules
- Eligibility Engine · Core scoring and admissions eligibility computation
app/eligibility_engine.py - Best-6 Score · Aggregate calculation for WASSCE subject grades
- Rule Checks · Program-specific eligibility evaluation against requirements
Persistence
ORM and SQLite-backed requirements store
- ORM Models · Structured access to admissions requirements data
app/models.py - Admissions DB · Runtime store for program and university requirements
instance/admissions.db
Seed Pipeline
Loads institutional rules into the database
- Seed Loader · Imports rule definitions into SQLite
seed_db.py - Rule Data · Source-of-truth admissions requirements content
Connections 15
- Admission UI → Client Logic: loads · Browser page includes interactive client behavior
- Client Logic → Routes: submits · Async request sends grades and program selection to Flask
- Routes → Eligibility Engine: calls · Routes delegate scoring and eligibility logic
- Routes → ORM Models: queries · Routes access requirements through the ORM boundary
- Eligibility Engine → Best-6 Score: computes · Engine derives aggregate score
- Eligibility Engine → Rule Checks: applies · Engine evaluates admission rules
- ORM Models → Admissions DB: persists · SQLAlchemy maps requirements data to SQLite
- Seed Loader → Rule Data: reads · Seeder consumes institutional JSON definitions
- Seed Loader → Admissions DB: loads · Seeder writes requirements into the database
- Main Entry → App Bootstrap: starts · Main entrypoint initializes the Flask app
- Run Entry → App Bootstrap: starts · Alternate launcher initializes the Flask app
- App Bootstrap → Routes: registers · Package initialization wires HTTP routes into the app
- Routes → Admission UI: renders · Routes return the main UI and result payloads
- Admission UI → Styles: uses · Page styling comes from the CSS asset
- Admission UI → Styles: styled by · Presentation layer dependency