# sharifaminuumar/university-admission-predictor architecture

> Architecture diagram of the GitHub repository sharifaminuumar/university-admission-predictor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sharifaminuumar/university-admission-predictor
- Repository: https://github.com/sharifaminuumar/university-admission-predictor

## Overview

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: [`app/routes.py`](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/routes.py) (Routes), [`app/templates/index.html`](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/templates/index.html) (Admission UI), [`app/eligibility_engine.py`](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/eligibility_engine.py) (Eligibility Engine), [`app/__init__.py`](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/__init__.py) (App Bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_ui["Browser UI"]
  node_browser_page["Admission UI<br/>template<br/>[index.html]"]
  node_client_js["Client Logic<br/>frontend JS<br/>[main.js]"]
  node_styles_css["Styles<br/>CSS<br/>[style.css]"]
end

subgraph group_group_web["Flask Delivery"]
  node_app_bootstrap["App Bootstrap<br/>package init<br/>[__init__.py]"]
  node_http_routes["Routes<br/>Flask HTTP<br/>[routes.py]"]
  node_main_entry["Main Entry<br/>launcher<br/>[main.py]"]
  node_run_entry["Run Entry<br/>launcher<br/>[run.py]"]
end

subgraph group_group_core["Eligibility Core"]
  node_eligibility_engine["Eligibility Engine<br/>business rules"]
  node_best6_score(("Best-6 Score<br/>scoring"))
  node_eligibility_rules{{"Rule Checks<br/>validation"}}
end

subgraph group_group_data["Persistence"]
  node_orm_models["ORM Models<br/>SQLAlchemy ORM<br/>[models.py]"]
  node_sqlite_db[("Admissions DB<br/>SQLite<br/>[admissions.db]")]
end

subgraph group_group_seed["Seed Pipeline"]
  node_seed_loader["Seed Loader<br/>ingestion<br/>[seed_db.py]"]
  node_rules_json["Rule Data<br/>JSON dataset"]
end

node_browser_page -->|"loads"| node_client_js
node_client_js -->|"submits"| node_http_routes
node_http_routes -->|"calls"| node_eligibility_engine
node_http_routes -->|"queries"| node_orm_models
node_eligibility_engine -->|"computes"| node_best6_score
node_eligibility_engine -->|"applies"| node_eligibility_rules
node_orm_models -->|"persists"| node_sqlite_db
node_seed_loader -->|"reads"| node_rules_json
node_seed_loader -->|"loads"| node_sqlite_db
node_main_entry -->|"starts"| node_app_bootstrap
node_run_entry -->|"starts"| node_app_bootstrap
node_app_bootstrap -->|"registers"| node_http_routes
node_http_routes -->|"renders"| node_browser_page
node_browser_page -->|"uses"| node_styles_css
node_browser_page -.->|"styled by"| node_styles_css

click node_browser_page "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/templates/index.html"
click node_client_js "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/static/main.js"
click node_styles_css "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/static/style.css"
click node_app_bootstrap "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/__init__.py"
click node_http_routes "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/routes.py"
click node_main_entry "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/main.py"
click node_run_entry "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/run.py"
click node_eligibility_engine "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/eligibility_engine.py"
click node_orm_models "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/models.py"
click node_sqlite_db "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/instance/admissions.db"
click node_seed_loader "https://github.com/sharifaminuumar/university-admission-predictor/blob/main/seed_db.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser_page,node_client_js,node_styles_css toneBlue
class node_app_bootstrap,node_http_routes,node_main_entry,node_run_entry toneAmber
class node_eligibility_engine,node_best6_score,node_eligibility_rules toneMint
class node_orm_models,node_sqlite_db toneRose
class node_seed_loader,node_rules_json toneIndigo
```

## Components

### Browser UI

Server-rendered page with client-side interaction

- [Admission UI](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/templates/index.html): template · Main HTML surface for entering grades and viewing results · `app/templates/index.html`
- [Client Logic](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/static/main.js): frontend JS · Handles interactions and async submission from the page · `app/static/main.js`
- [Styles](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/static/style.css): CSS · Presentation and responsive layout styling · `app/static/style.css`

### Flask Delivery

HTTP boundary and app startup

- [App Bootstrap](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/__init__.py): package init · Flask app package initialization and wiring · `app/__init__.py`
- [Routes](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/routes.py): Flask HTTP · Request handling and response packaging for eligibility checks · `app/routes.py`
- [Main Entry](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/main.py): launcher · Local execution entrypoint · `main.py`
- [Run Entry](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/run.py): launcher · Alternative execution entrypoint · `run.py`

### Eligibility Core

Deterministic admissions scoring and rules

- [Eligibility Engine](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/eligibility_engine.py): business rules · Core scoring and admissions eligibility computation · `app/eligibility_engine.py`
- **Best-6 Score**: scoring · Aggregate calculation for WASSCE subject grades
- **Rule Checks**: validation · Program-specific eligibility evaluation against requirements

### Persistence

ORM and SQLite-backed requirements store

- [ORM Models](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/app/models.py): SQLAlchemy ORM · Structured access to admissions requirements data · `app/models.py`
- [Admissions DB](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/instance/admissions.db): SQLite · Runtime store for program and university requirements · `instance/admissions.db`

### Seed Pipeline

Loads institutional rules into the database

- [Seed Loader](https://github.com/sharifaminuumar/university-admission-predictor/blob/main/seed_db.py): ingestion · Imports rule definitions into SQLite · `seed_db.py`
- **Rule Data**: JSON dataset · Source-of-truth admissions requirements content

## Connections

- 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