Gap Detection System

Graduation-project web system for detecting likely prerequisite gaps when a student returns to the Syrian curriculum after studying abroad.

The system does not judge one curriculum as better than another. It compares a student's actual studied path with the target Syrian curriculum path, then highlights prerequisite topics that may need teacher support.

Current Structure

frontend/
  index.html
  assets/
    app.js
    styles.css
  stitch_gap_detection_system/
    ...original Stitch exports and screenshots

backend/
  app/
    main.py
    logic/
    models/
    routes/
  Dockerfile
  requirements.txt

prototype/
  junior_curriculum_gap_prototype_v1.py

docs/
  api.md
  deployment.md

Frontend

The frontend is a static GitHub Pages-ready demo shell. It preserves the visual direction of the Stitch prototype and wires the main teacher workflow to the backend endpoints.

The Knowledge Graph section uses Cytoscape.js in the browser to render interactive node-edge graphs from the backend's graph-ready JSON. It supports student-specific graphs and curriculum-slice graphs without requiring Neo4j infrastructure at this phase.

The Analytics link opens frontend/analytics.html, a standalone Arabic reference page for studies, statistics, and infographics that motivate the need for curriculum gap detection.

Open locally:

Start-Process .\frontend\index.html

One-click local preview on Windows:

.\run_local_preview.ps1

Or double-click:

run_local_preview.bat

For GitHub Pages, configure Pages to publish from the frontend/ folder if your repository settings allow it. If not, publish from a branch or copy the static frontend files into the Pages source branch during deployment.

Backend

The backend uses FastAPI and refactors the original notebook-style logic into maintainable modules.

Run locally:

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8080

Health check:

GET http://localhost:8080/health

PostgreSQL MVP Foundation

The backend now includes a PostgreSQL-ready data layer using SQLAlchemy 2.x and Alembic. This is optional at runtime: the existing Google Sheet rule-based pipeline remains the default.

Configure PostgreSQL:

$env:DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/kgds"

Run migrations from backend/:

alembic upgrade head

Import the current Google Sheet curriculum/prototype data:

Invoke-RestMethod -Method Post -Uri http://127.0.0.1:8080/curriculum/import -ContentType "application/json" -Body "{}"

Use PostgreSQL as the rule-engine data source:

$env:KGDS_DATA_SOURCE="postgres"

See docs/database_architecture.md and docs/kgds_schema.dbml for the schema and ERD-ready DBML.

Data Source

By default, the backend reads the same Google Sheet used by the prototype:

• topics sheet
• prerequisite edges sheet
• student cases sheet

For Cloud Run or offline demos, set local CSV paths through environment variables:

GAP_TOPICS_CSV=/app/data/topics.csv
GAP_PREREQ_CSV=/app/data/prerequisites.csv
GAP_STUDENT_CASES_CSV=/app/data/student_cases.csv

Main API Routes

• GET /health
• POST /analyze-student-case
• POST /student-graph
• POST /curriculum-graph

Deployment Direction

• Frontend: GitHub Pages static hosting.
• Backend: Cloud Run-ready Dockerfile in backend/.
• Graph layer: backend returns graph-ready nodes and edges; the current frontend renders them with Cytoscape.js, and Neo4j storage can be added later without changing the teacher workflow contract.