How bhanutejagiddaluru/course-evaluation-ai-analytics-system works
1. This repository is organized around a data-to-analytics pipeline for student course feedback, not around a single application server. The core flow is: raw structured feedback files are cleaned, loaded into PostgreSQL, shaped through SQL views, then exposed through FastAPI, Streamlit, and a text-to-SQL AI assistant.
2. The primary input is a flat CSV/Excel-style student feedback dataset. The README describes a privacy-safe “bronze” cleaned layer, which implies the raw data is normalized and validated before any analytics or AI access. The key architectural boundary is that the AI and UI never query raw files directly.
3. PostgreSQL is the central system of record for the analytics layer. The database holds the cleaned bronze data and the derived SQL views that implement the trusted metrics used by the API and dashboard. This makes the database the main contract between ingestion, analytics, and presentation layers.
4. The analytics logic is encoded in SQL views under database/views/. These views produce the domain-specific outputs: course performance, instructor alias performance, department summaries, row-level scoring, and course alerts. This is the “silver/gold” shaping layer in the repository’s architecture.
5. The pipelines/scripts/run_sql_views.py and pipelines/scripts/test_sql_views.py scripts form a lightweight batch orchestration boundary. Their job is to materialize and verify the SQL layer, so the rest of the system can depend on stable relational outputs rather than ad hoc queries.
6. api/main.py is the FastAPI access layer. It reads from the analytics views and exposes domain endpoints such as health, course performance, instructor performance, department summary, and alerts. This layer acts as a controlled backend for consumers that should not talk to the database directly.
7. dashboard/streamlit_app.py is the interactive presentation layer. It pulls from the FastAPI/database layer to render charts, summaries, alert tables, and comparison views. The dashboard is therefore a consumer of the analytics API, not the owner of business logic.
8. The AI feature lives in src/course_eval_ai/agents/text_to_sql_agent.py. Its role is to translate natural language questions into safe SQL against approved analytics views. The important boundary is enforcement: only SELECT-style access is allowed, and destructive or unrestricted queries are blocked.
9. The system’s AI flow is intentionally constrained. The agent generates SQL, shows it before execution, and is restricted to trusted tables/views. This keeps LLM behavior within the analytics contract and avoids direct reasoning over raw uploads or unrestricted schema objects.
10. The project’s delivery model is local-first for the backend stack: PostgreSQL, FastAPI, and Streamlit are run separately, each with its own runtime and port. That separation matters for the diagram because it shows clear boundaries between persistence, API, and UI services.
11. There is also a static site boundary in the repository root: index.html plus .github/workflows/static.yml indicate GitHub Pages deployment for a project landing page or documentation shell. This is separate from the operational analytics stack and should be drawn as a static presentation surface, not as part of the data pipeline.
12. The repository includes supporting packaging and deployment artifacts such as requirements.txt, pyproject.toml, and the docs/, infra/, database/, and pipelines/ folders described in the README. These indicate the project is intended to be reproducible and environment-driven, with configuration likely shared across the API, dashboard, and agent layers.
Main entry points: index.html Landing page · static.yml Pages deploy
Components 16
Data pipeline
Ingestion, storage, shaping, and validation for trusted analytics data.
- Student feedback · Flat CSV or Excel-style course feedback files that enter the pipeline.
- Clean layer · Privacy-safe normalization and validation before any analytics access.
- PostgreSQL · Central relational store for cleaned data and derived analytics objects.
- SQL views · Trusted relational shaping for course, instructor, department, scoring, and alerts.
- View runner · Materializes the SQL layer so downstream consumers see stable outputs.
- View tests · Verifies the SQL views and their expected analytical behavior.
Serving layer
API, dashboard, and AI assistant built on curated analytics views.
- FastAPI · Controlled backend exposing analytics endpoints to consumers.
- Health · Service status and readiness surface.
- Course stats · Course performance and alert-oriented analytics surface.
- Instructor stats · Instructor alias performance and comparison views.
- Dept summary · Department-level aggregation and reporting surface.
- Alerts · Row-level and course-level alert output for consumers.
- Streamlit app · Charts, summaries, alerts, and comparisons for human exploration.
- Text-to-SQL · Natural language to safe SQL over approved analytics views.
Delivery
Static presentation and repository publishing surfaces.
- Landing page · Repository-facing static presentation and documentation shell.
index.html - Pages deploy · Workflow that publishes the static site.
.github/workflows/static.yml
Connections 16
- Student feedback → Clean layer: ingest · Raw files are normalized and validated before analytics access.
- Clean layer → PostgreSQL: load · Cleaned bronze data is persisted in PostgreSQL.
- PostgreSQL → SQL views: shape · SQL views derive trusted analytics outputs from stored data.
- View runner → SQL views: materialize · Batch scripts create and refresh the view layer.
- View tests → SQL views: verify · Tests validate the analytics SQL layer.
- SQL views → FastAPI: serve · FastAPI reads only curated analytics objects.
- FastAPI → Health: expose · Health endpoint reports service status.
- FastAPI → Course stats: expose · Course performance endpoint returns trusted metrics.
- FastAPI → Instructor stats: expose · Instructor performance endpoint returns alias-based metrics.
- FastAPI → Dept summary: expose · Department summary endpoint returns aggregated analytics.
- FastAPI → Alerts: expose · Alerts endpoint surfaces course and scoring warnings.
- SQL views → Streamlit app: power · Dashboard consumes the analytics layer through the backend boundary.
- FastAPI → Streamlit app: feed · Streamlit renders summaries and comparisons from the API.
- SQL views → Text-to-SQL: allow · The agent is restricted to approved analytics views.
- Text-to-SQL → FastAPI: query · Generated SQL is executed through controlled analytics access.
- Landing page → Pages deploy: publish · Static landing page is deployed through GitHub Pages workflow.