StudyBuddy Django App

StudyBuddy is a Django study-planning platform for structured study activity, note capture, progress tracking, and deterministic study insights.

The product helps users register, manage study sessions, capture notes, review personal progress, and generate deterministic AI/NLP insights from their own study material.

The application uses clear app boundaries, PostgreSQL-backed persistence, tested domain behaviour, role-aware access foundations, explainable NLP output, and deployment-oriented settings.

StudyBuddy is not a learning management system, classroom administration platform, course marketplace, or general-purpose chatbot.

Repository: https://github.com/AAdewunmi/StudyBuddy-Study-Planner-Project

Live MVP URL: https://studybuddy-django-app.onrender.com

Product Summary

StudyBuddy focuses on a clear authenticated user workflow:

1. Register and log in.
2. Land on a personal dashboard.
3. Create study sessions.
4. Add notes to sessions.
5. Generate deterministic AI/NLP insights from notes.
6. Review dashboard metrics, session history, notes, and recent insights.

The AI/NLP capability is intentionally lightweight and explainable. It uses deterministic text normalisation, keyword extraction, extractive summaries, source text hashing, rule-based confidence scoring, and plain-English explanations.

Demo

• StudyBuddy Product Landing Page

• Admin Platform Operations Dashboard

• Student and Tutor Study Workspace

Current Release Status

The MVP now includes deterministic AI/NLP study insights and a deployment verification path.

Current verification tag: v0.1.0-mvp. See docs/final-verification.md for the evidence checklist.

Users can now:

• create study sessions
• add notes to sessions
• generate deterministic insights from those notes
• view summaries, keywords, confidence scores, and explanations
• revisit generated insights from a dedicated dashboard

AI/NLP Insight Contract

The AI/NLP insight feature analyses notes attached to one user-owned study session. It stores a reusable StudyInsight containing an extractive summary, ranked keywords, a confidence score, an explanation, and a SHA-256 source hash derived from normalised note text.

The feature is deterministic by design. If the same session notes are analysed again without changes, StudyBuddy reuses the existing insight for that session and source_hash instead of creating a duplicate row.

The MVP boundary is intentionally narrow:

• no large language model or external AI API
• no background worker
• no uploaded-file analysis
• no cross-user or cross-account analysis
• no semantic embeddings, topic clustering, or recommendation engine
• no claim that confidence is a probability or factual correctness score

The detailed product and technical contract lives in docs/ai-nlp-contract.md.

Current Capabilities

• StudySession and StudyNote domain models.
• StudyInsight persistence for deterministic note insights.
• Email-first signup, login, logout, and profile flows.
• Role-aware access helpers through user.studybuddy_roles.
• Role-aware navigation context for product admin and regular user surfaces.
• Owner-scoped session list, create, detail, and update workflows.
• Note create, update, and delete workflows scoped through parent session ownership.
• Deterministic AI/NLP pipeline for source hashing, keyword extraction, extractive summaries, confidence scoring, and explanations.
• Idempotent insight generation for unchanged note text.
• Insights dashboard scoped to the authenticated user.
• Selector helpers for user-scoped session and note queries.
• Service helpers for session, insight, user dashboard, and platform dashboard aggregate metrics.
• A data-backed dashboard that renders prepared personal metrics, recent activity, role-aware admin operations metrics, and platform health summaries.
• Custom production error pages for HTTP 400, 403, 404, and 500 responses.
• GitHub Actions CI for checks, migrations, linting, formatting, Docker image build, tests, coverage XML generation, and Codecov upload.
• Dependabot automation for Python dependency and GitHub Actions update PRs.
• Production settings, a Docker image path, and a Render Blueprint for deployment-style runtime checks.
• Health check endpoint at /health/ for deployment and monitoring checks.
• Strict custom design-system templates using static/css/theme.css, not Bootstrap visual classes.

Tech Stack

• Python 3.11+ supported by project metadata
• Python 3.13 in Docker
• Django 5.x
• PostgreSQL 16
• Django templates
• pytest and pytest-django
• factory_boy
• django-environ
• Black and Ruff
• Custom Django template design system in static/css/theme.css
• Docker Compose

Quick Start

From a clean clone, create the local environment file, build and start the Docker-backed stack, apply migrations, then run the verification suite.

git clone https://github.com/AAdewunmi/StudyBuddy-Study-Planner-Project.git
cd StudyBuddy-Study-Planner-Project
cp .env.example .env
make build
make up
make migrate
make test

The app runs at:

http://localhost:8000

Local Setup

Run the Docker-backed local stack after creating .env.

make up

The Makefile provides repeatable aliases for the same Docker commands used by the runbooks and review checks.

make check              # Django system check with config.settings.local
make check-migrations   # Confirm migrations are clean
make migrate            # Apply local PostgreSQL migrations
make format-check       # Run Black in check mode
make lint               # Run Ruff checks
make test-insights      # Run the insights test suite
make test               # Run the full pytest suite
make ci                 # Run the local GitHub Actions-style verification chain
make release-verify     # Run release verification

The equivalent raw Docker commands are:

docker compose exec -T web python manage.py check --settings=config.settings.local
docker compose exec -T web python manage.py makemigrations --check --dry-run --settings=config.settings.local
docker compose exec -T web python manage.py migrate --noinput --settings=config.settings.local
docker compose exec -T web python -m ruff check .
docker compose exec -T web python -m black . --check
docker compose exec -T web python -m isort . --check-only
docker build -t studybuddy-ci .
docker compose exec -T web env DJANGO_SETTINGS_MODULE=config.settings.test TEST_DATABASE_URL=postgres://studybuddy:studybuddy@db:5432/studybuddy_test pytest --cov=apps --cov=config --cov-report=xml -q

Host-side pytest also uses PostgreSQL. When running from a local Python environment, point the test settings at Docker Compose's published database port:

TEST_DATABASE_URL=postgres://studybuddy:studybuddy@localhost:5432/studybuddy_test python3 -m pytest --cov=apps --cov=config --cov-report=term-missing -q

Run the release verification script.

make release-verify

Environment Settings

StudyBuddy isolates environment behavior with explicit settings modules:

• config.settings.local is for Docker-backed local development.
• config.settings.test is for tests and CI, using PostgreSQL.
• config.settings.production is for deployment and requires production environment variables.

Docker Compose runs the app with config.settings.local. CI and local test commands use config.settings.test.

Production deployment is defined in render.yaml. The Blueprint creates the Render Docker web service, managed PostgreSQL database, /health/ check, pre-deploy migration command, and non-secret production environment variables. Render prompts for DJANGO_SECRET_KEY and email provider values, then derives DATABASE_URL from the managed database instead of storing secret values in the repository. The /health/ release field uses RENDER_GIT_COMMIT on Render unless an explicit RELEASE_SHA override is provided.

Render is used because it fits the MVP boundary: the repo owns the Django app, Docker image, Blueprint, migrations, static files, health endpoint, and runtime contract; Render owns hosting, TLS, routing to PORT, deploy orchestration, managed PostgreSQL, secret injection, and health check execution. The detailed deployment rationale and platform boundary are documented in docs/deployment.md.

Architecture Notes

The main project documentation is:

• Architecture
• Domain model
• Design system
• AI/NLP contract
• Deployment
• Operational runbook
• Archived implementation outline

The architecture, deployment, and final verification docs are the current sources of truth. The archived implementation outline preserves earlier planning context. The AI/NLP contract records the deterministic insight behaviour. The Makefile keeps local setup, review, and CI-style verification commands consistent. The README keeps the current runtime shape and verification path front and center.

Verification Baseline

The release verification checklist lives in docs/final-verification.md. It covers local checks, hosted CI, Render deployment checks, live /health/, and a browser smoke test against the deployed product.

The current targeted insights verification command is:

make test-insights

This command proves the feature contract at the test level: model persistence, source hashing, keyword extraction, extractive summarisation, confidence scoring, explanation text, idempotent generation, owner-only access, dashboard visibility, and view-level route behaviour are covered by apps/insights/tests.

The full local suite should also pass:

make test

Core Routes

• home -> /
• users:signup -> /users/signup/
• users:login -> /users/login/
• users:logout -> /users/logout/
• users:profile -> /users/profile/
• dashboard:index -> /dashboard/
• sessions:list -> /sessions/
• sessions:create -> /sessions/new/
• sessions:detail -> /sessions/<pk>/
• sessions:update -> /sessions/<pk>/edit/
• sessions:add_note -> /sessions/<pk>/notes/new/
• sessions:update_note -> /sessions/<pk>/notes/<note_pk>/edit/
• sessions:delete_note -> /sessions/<pk>/notes/<note_pk>/delete/
• insights:list -> /insights/
• insights:generate -> /insights/sessions/<session_id>/generate/
• health-check -> /health/
• custom error templates -> 400.html, 403.html, 404.html, 500.html

Repository Structure

StudyBuddy-Study-Planner-Project/
    apps/
        dashboard/       Personal/admin dashboard views, context services, and tests.
        insights/        Deterministic AI/NLP insights, metrics, selectors, and tests.
        roles/           Role model, user-role relationships, and nav context.
        sessions/        Study sessions, notes, selectors, services, and tests.
        users/           Custom user model, auth forms, profile, and user URLs.
    config/
        settings/        Base, local, test, and production Django settings.
        urls.py          Project URL routing.
        asgi.py          ASGI application entrypoint.
        wsgi.py          WSGI application entrypoint.
    docs/                Architecture, domain, design, setup, and runbooks.
    static/css/theme.css Project-owned design system styles.
    templates/           Base, error, dashboard, insight, session, user, and public templates.
    tests/               Cross-app pytest coverage, health checks, and error pages.
    Dockerfile           Container image definition.
    docker-compose.yml   Local PostgreSQL-backed development stack.
    render.yaml          Render Blueprint for the production web service and database.
    scripts/             Project command wrappers, including release verification.
    manage.py            Django management command entrypoint.
    pyproject.toml       Project metadata and tool configuration.
    pytest.ini           Pytest and Django test configuration.
    RUNBOOK.md           Operational runbook for local checks and handoff.
    requirements.txt     Python dependency list.

CI Coverage

CI generates coverage.xml with pytest-cov and uploads it to Codecov with the CODECOV_TOKEN GitHub Actions secret. The Codecov repository must be active in Codecov before uploads will be accepted.

Dependency Updates

Dependabot is configured in .github/dependabot.yml to open weekly PRs for Python dependencies from requirements.txt and GitHub Actions versions. Those PRs run through the same CI, Docker build, coverage, and Codecov checks as other pull requests.

Next Steps

1. Shape the tutor dashboard carefully. If tutors do not currently have assigned students, cohorts, or teaching groups in the data model, the tutor dashboard cannot honestly show student-wide analytics yet.

   Without new backend/domain work, a tutor dashboard can show:

   • tutor account activity
   • the tutor's own study, session, and insight metrics
   • role-aware dashboard styling

   It cannot show:

   • student progress
   • at-risk students
   • class activity
   • tutor-managed courses

   Those views require a model connecting tutors to students or sessions.

2. Fix or confirm the live Render service URL. The documented URL is https://studybuddy-django-app.onrender.com; update the docs and render.yaml host settings if Render generated a different hostname.

3. Run the release verification script against the live service:

   LIVE_URL="https://your-render-service.onrender.com" make release-verify

4. Complete the live browser smoke test: signup, login, dashboard, session creation, note creation, insight generation, logout, and protected-page redirects.

5. Automate the post-deploy browser smoke path with Playwright or an equivalent lightweight end-to-end check.

6. Upgrade Render plans only after live MVP validation or when traffic, runtime, or database retention needs exceed the free plan limits.