Initial commit

Author: AmmarSaleh50

.env.example

@@ -0,0 +1,28 @@
+# ─── Backend (.env at repo root — consumed by FastAPI + seed + Vercel) ─────
+# Your Supabase project. Create one at https://supabase.com (free tier works).
+SUPABASE_URL=https://YOUR-PROJECT.supabase.co
+SUPABASE_SERVICE_KEY=your-service-role-key
+
+# Argon2id hash of the password that gates the app. Generate with:
+#   uv run python -m app.tools.hashpw 'your-strong-password'
+APP_PASSWORD_HASH=
+
+# Random secret for session signing. Generate with:
+#   python -c 'import secrets; print(secrets.token_urlsafe(48))'
+SESSION_SECRET=
+
+# Comma-separated list of origins allowed to hit the API.
+CORS_ORIGINS=http://localhost:5173
+
+# Optional: public URL of the deployed app (for OAuth/MCP callback URLs).
+# In local dev you can leave this blank — it's derived from the request.
+PUBLIC_URL=
+
+# Optional: only needed to run `psql` migrations locally.
+SUPABASE_DB_PASSWORD=
+
+# Optional: local directory that mirrors the course_files bucket (for scripts/sync.py).
+STUDY_ROOT=
+
+# ─── Frontend (web/.env.local) ─────────────────────────────────────────────
+VITE_API_BASE_URL=http://localhost:8000

.gitignore

@@ -0,0 +1,50 @@
+# dependencies
+node_modules/
+.pnpm-store/
+web/.vite/
+
+# builds
+dist/
+build/
+out/
+web/dist/
+*.tsbuildinfo
+
+# env
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+api/.venv/
+mcp/.venv/
+
+# editors
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# vercel
+.vercel/
+
+# logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+.vercel
+
+# tool-local state
+.claude/
+supabase/

CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md
+
+Notes for Claude Code working in this repo. See `README.md` for stack basics and `INSTALL.md` for self-host setup.
+
+## Deployment
+
+**Hosting:** Vercel (frontend + Python API functions). Project is linked in `.vercel/project.json`.
+
+**How deploys happen:** Vercel auto-deploys on every push to `main` via the GitHub integration. Nothing deploys from your local working copy — code changes stay local until pushed.
+
+**Implication:** Edits to files under `app/` (Python backend / MCP tools) and `web/src/` (frontend) only affect the live site at `<your-deployment>.vercel.app` after a `git push` to `main`. The MCP server the user connects to from Claude.ai runs on the deployed Vercel instance — so MCP tool behavior won't change for them until a push.
+
+**When to push:** don't deploy after every fix. Push when:
+- The user asks you to deploy / push / "ship it"
+- A batch of changes is ready and tested locally
+- A bug fix is urgent enough that the live site needs it now
+
+When in doubt, ask. Don't `git push` on your own for routine fixes.
+
+**Deploy commands:**
+```bash
+git push origin main           # triggers auto-deploy
+vercel --prod                  # manual deploy (rarely needed)
+vercel logs <url>              # inspect a deployment
+```
+
+**Local verification before pushing:**
+```bash
+cd web && pnpm build           # frontend builds clean
+uv run pytest                  # if/when backend tests exist
+```
+
+## Two copies of the fall-behind logic
+
+`app/services/fall_behind.py` (Python, runs on Vercel / MCP) and `web/src/lib/fall-behind.ts` (TS, runs in the browser) are intentional mirrors. Keep them in sync when changing rules — constants, grace periods, severity thresholds.

CODE_OF_CONDUCT.md

@@ -0,0 +1,64 @@
+# Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to make participation in our project and
+our community a respectful experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of
+experience, nationality, personal appearance, race, religion, or sexual
+identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported by opening a private
+GitHub Security Advisory on the repository, or by contacting the project
+maintainer directly via the email listed on the maintainer's GitHub profile.
+All complaints will be reviewed and investigated and will result in a response
+that is deemed necessary and appropriate to the circumstances. The project
+team is obligated to maintain confidentiality with regard to the reporter of
+an incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.4, available at
+https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org

CONTRIBUTING.md

@@ -0,0 +1,74 @@
+# Contributing
+
+Thanks for considering a contribution — genuinely. Whether it's a one-line typo fix, a new MCP tool, or just an issue saying "this didn't work on my machine, here's what I saw" — all of it helps.
+
+This file just has a couple of notes so you know what to expect and we can keep the back-and-forth short.
+
+## What's in scope
+
+Basically anything that makes the app better for someone self-hosting it. A non-exhaustive list of things I'd love help with:
+
+- **Bug fixes** — obvious one. If you hit a bug, please file an issue even if you can't fix it yourself.
+- **Self-host polish** — clearer docs, better error messages when an env var is missing, a `docker-compose.yml`, one-click deploy buttons for hosts other than Vercel (Fly, Railway, self-hosted Postgres, etc.).
+- **Accessibility + keyboard shortcuts** — the UI is dark, dense, and keyboard-navigable-ish, but could be better.
+- **i18n / localization** — the Slot `kind` labels are German (`Vorlesung`, `Übung`) by default. Making those user-configurable or translatable would help non-EU users a lot.
+- **New MCP tools** — if you find yourself wishing Claude could do `X` and there's a natural way to expose it, just add it. Pattern is in `app/mcp_tools.py`.
+- **Performance / bundle size** — the frontend chunk is bigger than it needs to be; someone who knows their way around Vite code-splitting could shave a lot.
+- **Tests** — there's no suite yet. Adding pytest + Vitest scaffolding is its own welcome PR.
+
+## Things worth a quick issue first
+
+Not "no" — just "let's talk first so you don't waste a weekend":
+
+- Major framework swaps (React → Svelte, FastAPI → Django).
+- Removing Supabase (doable, but touches auth + storage + Postgres all at once).
+- New top-level entities beyond the current data model (Course / Schedule slot / Lecture / Study topic / Deliverable / Task / Klausur).
+- Multi-user / team / sharing features — the single-user-per-deploy assumption is load-bearing in a bunch of places, and shifting it is a big project.
+
+A one-liner issue like *"would you take a PR that X?"* is all it takes.
+
+## Dev setup
+
+See [INSTALL.md](./INSTALL.md) for the full walkthrough. TL;DR:
+
+```bash
+uv sync
+cp .env.example .env   # fill in Supabase creds, APP_PASSWORD_HASH, SESSION_SECRET
+uv run python -m db.seed
+uv run uvicorn app.main:app --reload
+
+cd web && pnpm install && pnpm dev
+```
+
+## Code conventions
+
+- **Python:** `ruff` is configured in `pyproject.toml` (line-length 100, py312 target). Run `uv run ruff check .` and `uv run ruff format .` before pushing.
+- **TypeScript/React:** `eslint` is configured in `web/`. Run `pnpm lint` from `web/`. Components are function components + hooks; state via React Query for server state and `useState`/`useReducer` for local.
+- **Commit messages:** short imperative subject line (≤70 chars), optional body explaining the *why*. See `git log` for the house style.
+- **Scope per PR:** one logical change. A bug fix + a refactor + a new feature should be three PRs.
+
+## The fall-behind mirror
+
+`app/services/fall_behind.py` (Python, runs on the server / in MCP) and `web/src/lib/fall-behind.ts` (TypeScript, runs in the browser) are **intentional mirrors**. Any change to the rules — severity thresholds, grace periods, which topics count — must be applied to both. PRs that only touch one side will get a request for the other.
+
+## Testing
+
+There's no automated test suite yet (honest). Until there is:
+
+- For backend changes: exercise the changed endpoint(s) manually via `curl` or the `/api/docs` Swagger UI, and check that the data round-trips through Supabase.
+- For frontend changes: run `pnpm build` to make sure TypeScript is still happy, then manually click through the affected views in `pnpm dev`.
+- For MCP tool changes: start the backend (`uv run uvicorn app.main:app --reload`), then either hit the tool via a `POST /mcp` JSON-RPC request with your bearer token (see `curl` snippet in `INSTALL.md`), or register the local endpoint with Claude Code (`claude mcp add --transport http study-dashboard-dev http://localhost:8000/mcp`) and call the tool in chat.
+
+If you're up for adding test infrastructure (pytest + a Supabase mock, Vitest for the frontend), that itself is a welcome PR.
+
+## Submitting a PR
+
+1. Fork, branch, commit.
+2. Run the relevant linter/build (`ruff`, `pnpm lint`, `pnpm build`).
+3. Push and open a PR against `main`.
+4. In the PR description, include: what the change does, how you tested it, anything reviewers should pay attention to.
+5. Be patient — this is a side project. Responses may take a few days.
+
+## License
+
+By submitting a PR you agree that your contribution is licensed under the same MIT license as the rest of the project (see [LICENSE](./LICENSE)).