Cognitive Performance Analyzer (CPA)

A modern, full‑stack exam‑analytics web application that helps students track exam readiness, review answers, and visualize performance across subjects. Built with Flask (Python) on the backend, SQLite (SQLAlchemy) for persistence, and a responsive single‑page frontend using vanilla JavaScript, Chart.js, and Jinja2 templates.

• Demo‑ready for local use — seeded database with sample users, subjects, questions and test results.
• Designed for small classrooms, practice platforms, or as a reference project for building analytics‑driven learning tools.

---

Table of contents

• Features
• Tech stack
• Repository layout
• Quick start (local)
• Configuration
• API reference
• Database schema
• Security & production notes
• Development notes & suggestions
• Contributing
• License

---

Features

• Student registration and login
• Timed tests (30 minutes), auto‑submit on timeout
• Answer review with correctness indicators
• Exam readiness score and subject‑level analytics visualized with Chart.js
• Admin panel to manage subjects, questions, users, and view test results
• All data persisted using SQLite via SQLAlchemy; DB is auto‑created and seeded on first run

---

Tech stack

• Language(s): Python (Flask) backend, JavaScript frontend, HTML/CSS
• Runtime: Flask (single‑file app app.py)
• Notable libraries:
  • Flask + Flask SQLAlchemy
  • Werkzeug security utilities (password hashing)
  • Chart.js for charts on the frontend

Dependencies are listed in requirements.txt.

---

Repository layout

Annotated top‑level tree (key files/directories):

app.py                      ← Flask application, models, routes, DB seed + server startup
requirements.txt            ← Python dependencies
templates/
  index.html                ← Single‑page frontend template (Jinja2)
static/
  css/style.css             ← Application styles
  js/app.js                 ← Frontend logic: routing, API calls, UI rendering, charts
instance/                   ← (empty) instance dir (app may use for runtime files)
README.md                   ← Project README (this file)

How it fits together:

• app.py contains SQLAlchemy models, DB seeding, page route (/) and REST API endpoints under /api/*. The single frontend page (templates/index.html) loads static/js/app.js, which drives the UI, calls the backend API, and renders analytics with Chart.js. On first run the SQLite database (cpa.db) is created and seeded.

---

Quick start (local)

Prerequisites: Python 3.8+ recommended, pip.

1. Clone the repo

   git clone https://github.com/tamas2006/CognitivePerformanceAnalyzer.git
   cd CognitivePerformanceAnalyzer

2. Create a virtual environment (recommended) and install dependencies

   python -m venv .venv
   source .venv/bin/activate    # macOS/Linux
   .venv\Scripts\activate       # Windows (PowerShell: .venv\Scripts\Activate.ps1)
   pip install -r requirements.txt

3. Run the app

   python app.py

4. Open the app

   http://127.0.0.1:5000
   

The SQLite database is auto‑created and seeded on first run.

Demo credentials (seeded)

• Student: user1 / pass123
• Student: user2 / pass123
• Admin: admin / admin123 (There is also an admin login path in the code using different credentials — see Security notes.)

---

Configuration

• Default DB URI: sqlite:///cpa.db (configured in app.py)
• SECRET_KEY: currently set directly in app.py as app.secret_key. For any deployment, never hard-code secrets; set them via environment variables or a config file (see Security notes).

Environment variables to add for production:

• FLASK_ENV=production
• Set a secure secret key (e.g., via export SECRET_KEY="...") and modify app.py to read from env.

---

API reference (summary)

All endpoints return JSON. These are implemented in app.py.

Authentication

• POST /api/login — Student login (JSON: username, password)
• POST /api/register — Student registration (JSON: name, username, password)
• POST /api/admin-login — Admin login (JSON: username, password)
• POST /api/logout — Logout

Subjects

• GET /api/subjects — List all subjects
• POST /api/subjects — Add subject (admin)
• DELETE /api/subjects/ — Delete subject (admin)

Questions

• GET /api/questions — List all questions
• GET /api/questions/subject/ — Questions for a subject
• POST /api/questions — Add question (admin)
• DELETE /api/questions/ — Delete question (admin)

Results / Tests

• GET /api/results — All results (admin)
• GET /api/results/user/ — Results for a user
• POST /api/results — Submit a test result (JSON: userId, subjectId, score, total, timeTaken, answers)

Users (admin)

• GET /api/users — List users and stats (admin)

---

Database schema (high-level)

Models are defined in app.py (SQLAlchemy):

• User
  • id, name, username (unique), password_hash, created_at
• Subject
  • id, name, icon, category, relationship -> questions, results
• Question
  • id, subject_id (FK), text, options (JSON string), correct (index), difficulty
• TestResult
  • id, user_id (FK), subject_id (FK), score, total, time_taken (sec), answers (JSON), date, created_at

The seed function (seed_db() in app.py) populates example users, 6 subjects, ~45 questions, and several sample test results.

---

Security & production notes (important)

• SECRET KEY: app.secret_key is hard-coded in app.py. In production, never hard-code secrets. Load from environment variables or a secure vault and use Flask config.
• Admin credentials: the code contains an admin login check with hard-coded credentials (see app.py). Move admin authentication to a proper user/role system and never commit plaintext credentials.
• Debug mode: ensure debug=False in production and run via a production WSGI server (Gunicorn / uWSGI) behind a reverse proxy.
• Database: SQLite is fine for demos and small deployments. For production or multi-user usage, migrate to PostgreSQL or another server-based RDBMS and update SQLALCHEMY_DATABASE_URI.
• Session management: use secure cookies, HTTPS, and set appropriate cookie flags (Secure, HttpOnly, SameSite).

---

Development notes & suggestions

These are recommended improvements to make the project production-ready and easier to maintain:

• Move route handlers and models into a package layout (e.g., cpa/ with models.py, routes/, services/) instead of a single app.py.
• Add unit tests for core logic (model methods, scoring, API responses).
• Add input validation and stronger error handling for API endpoints.
• Replace the ad-hoc admin login with role-based access control (store admins in the users table with a role/flag).
• Use migrations (Flask-Migrate / Alembic) instead of auto-create for schema changes.
• Add CI (GitHub Actions) to run linting and tests on push.
• Sanitize and validate user-supplied data when adding questions/subjects.
• Use hashed session stores or JWTs if scaling beyond single-server sessions.

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/your-feature)
3. Commit changes and push to your fork
4. Open a pull request with a clear description of changes

Please include tests for any bug fixes or new features.

---