study-dashboard/docs/agent_instructions.md

Study Dashboard – Agent Instructions

This document summarizes the project conventions and provides a hand-off for the next sprint. When starting new work, follow these steps before touching any code:

1. Read the docs: review README.md, docs/architecture.md, and this file to understand the stack (PySide6, MVVM, dependency-injector, SQLite seed DB).
2. Prepare the env: run bash scripts/bootstrap.sh to create/update .venv. Use the helper scripts (bash scripts/run-app.sh, bash scripts/run-qa.sh) so env vars and caches are handled automatically.
3. Run tests by default: bash scripts/run-qa.sh executes pytest, mypy, flake8, and black in one go (forward extra pytest args as needed). Add or extend tests alongside code.

Guiding Principles

• Architecture: MVVM with a thin PySide6 view (gui/main_view.py), a Qt-based ViewModel (gui/main_view_model.py), and a repository layer backed by SQLite. All data access goes through StudyRepository.
• Dependency injection: extend src/study_dashboard/di_container.py when adding new services or ViewModels. Create providers for configs beforehand.
• Database: the bootstrapper auto-creates study.db with seed data. When schema changes, update services/database.py and adjust tests.
• Generated files: everything temporary belongs under bin/ (already git-ignored). The PySide deploy spec lives in deploy/pysidedeploy.spec, bash scripts/build.sh wraps it and writes output to bin/deploy.
• Cleanup: if a task bypassed the helper scripts and left __pycache__ folders in src/ or tests/, run bash scripts/clean.sh before committing.
• UI language: keep user-facing strings in German.
• Style: enforce PEP8 via flake8 src tests. Keep docstrings and comments concise; prefer descriptive identifiers.

Workflow Expectations

• For every feature: rely on the helper scripts (run-app, run-qa, build) to keep commands consistent, use bash scripts/clean.sh whenever cached artefacts slip into tracked folders, and update documentation/tests alongside code.
• Update documentation if behavior or setup changes (README.md or docs/architecture.md).
• Prefer smaller commits tied to single concerns.

Next Sprint Placeholder

When kicking off a new sprint:

1. Identify the next feature or bug fix.
2. Write a brief plan (e.g., extend ViewModel for KPI charts, add editing dialogs, etc.).
3. List tasks in order inside the todo tool / project tracker.
4. Execute while keeping the principles above in mind.

Add future objectives below as they are defined.