tutortool/conductor/attendance-tool.md

Implementation Plan: Attendance Tracking Tool (Continuation)

Objective: Complete the backend API, scaffold the SvelteKit frontend, implement all frontend views based on the provided design handoff, and set up deployment manifests. This plan picks up from where the .worktrees/feature-tutortool workspace left off (Tasks 1-8 completed).

Scope:

• Complete backend APIs for attendance, notes, and exports.
• Serve SvelteKit SPA fallback via Axum.
• Scaffold SvelteKit frontend.
• Implement UI pages for Admin tools (Dashboard, Courses, Rooms, Sessions, Attendance, Notes, Export) and Student Check-in.
• Configure local development (Makefile, Docker Compose) and K8s manifests.

---

1. Backend Completion

Task 9: Admin Attendance & Notes APIs

Files to Create/Modify:

• backend/src/routes/attendance.rs
• backend/src/routes/notes.rs

Implementation Steps:

• Add POST /api/admin/slots/:id/attendance (manual entry) and DELETE /api/admin/slots/:slot_id/attendance/:student_id.
• Add GET /api/admin/sessions/:id/attendance (per-week matrix) and GET /api/admin/students/:id/attendance.
• Add PUT /api/admin/slots/:slot_id/notes/:student_id (upsert note).
• Add GET /api/admin/slots/:slot_id/notes and GET /api/admin/students/:id/notes.
• Write corresponding unit tests.

Task 10: Export API

Files to Create/Modify:

• backend/src/routes/export.rs

Implementation Steps:

• Add GET /api/admin/export/session/:id/csv and /md (merged per-session weekly attendance).
• Add GET /api/admin/export/course/:id/csv and /md (full course matrix with Bonus points calculation: +3 if unexcused absences <= 1).
• Add GET /api/admin/backup (using VACUUM INTO '/tmp/backup-<timestamp>.sqlite' then streaming as application/octet-stream).
• Ensure all endpoints verify TutorClaims and course access.

Task 11: Static File Serving & Route Assembly

Files to Modify:

• backend/src/main.rs
• backend/src/routes/mod.rs

Implementation Steps:

• Merge attendance, notes, and export routers in routes/mod.rs.
• Configure tower_http::services::ServeDir in main.rs to serve the SvelteKit static build.
• Set up ServeFile::new(format!("{static_dir}/index.html")) as the SPA fallback service.

---

2. Frontend Development

Task 12: Scaffold SvelteKit Frontend

Files to Create/Modify:

• frontend/package.json, svelte.config.js, vite.config.ts, src/app.html, src/lib/types.ts, src/lib/api.ts, src/lib/auth.ts

Implementation Steps:

• Initialize SvelteKit with @sveltejs/adapter-static configured for SPA fallback.
• Setup Vite proxy /api -> http://localhost:3000.
• Create TypeScript types mirroring the backend database models.
• Implement API client fetch wrapper (api.ts).
• Set up Svelte store for JWT auth (auth.ts).

Task 13: Login Page & Admin Auth Guard

Files to Create/Modify:

• frontend/src/routes/login/+page.svelte
• frontend/src/routes/admin/+layout.svelte

Implementation Steps:

• Implement the tutor login form and API integration.
• Protect /admin routes using an onMount check redirecting unauthenticated users to /login.

Task 14: Dashboard & Slot Management

Files to Create/Modify:

• frontend/src/routes/admin/+page.svelte

Implementation Steps:

• Display all sessions/slots.
• Implement toggles for slot status (closed, open, locked).
• Display check-in link and copy button when a slot is open.

Task 15: Courses & Students UI

Files to Create/Modify:

• frontend/src/routes/admin/courses/+page.svelte

Implementation Steps:

• List courses and forms to create new courses.
• Per-course student management: list students, add individual student, import from CSV, and delete students.

Task 16: Room Layout Editor

Files to Create/Modify:

• frontend/src/lib/RoomCanvas.svelte
• frontend/src/routes/admin/rooms/+page.svelte

Implementation Steps:

• Implement SVG-based RoomCanvas.svelte supporting interactive (draggable/editable) mode, student check-in mode, and tutor notes mode.
• Build room management UI: list rooms, create rooms, and edit JSON room layouts visually.

Task 17: Sessions & Slots UI

Files to Create/Modify:

• frontend/src/routes/admin/sessions/+page.svelte

Implementation Steps:

• Form to create sessions (course, week_nr, date).
• Form to add slots within a session (room, tutor, start_time, end_time).

Task 18: Student Check-in Page

Files to Create/Modify:

• frontend/src/routes/s/[code]/+page.svelte

Implementation Steps:

• Fetch slot info. If no identity cookie exists, show name dropdown filtered to the course.
• Display RoomCanvas indicating free/occupied seats.
• Handle FCFS seat locking API calls (POST /api/checkin) and update UI.
• Support read-only mode for locked/closed slots.

Task 19: Attendance & Notes UI

Files to Create/Modify:

• frontend/src/routes/admin/attendance/+page.svelte
• frontend/src/routes/admin/notes/+page.svelte

Implementation Steps:

• Build matrix tables (per-week and per-student) for manual attendance marking/removal.
• Build notes UI utilizing RoomCanvas for clicking on seats to leave inline text notes.

Task 20: Export UI

Files to Create/Modify:

• frontend/src/routes/admin/export/+page.svelte

Implementation Steps:

• Provide buttons to download weekly CSV/Markdown, full course matrix, and SQLite backup directly from the admin interface.

---

3. DevOps & Deployment

Task 21: Local Dev Environment

Files to Create/Modify:

• Makefile
• docker-compose.yml

Implementation Steps:

• Write Makefile with commands: dev, dev-backend, dev-frontend, test, build, compose-up.
• Create docker-compose.yml for testing the production image locally using SQLite mounted via volume.

Task 22: Dockerfile & K8s Manifests

Files to Create/Modify:

• Dockerfile
• k8s/deployment.yaml, k8s/service.yaml, k8s/ingress.yaml, k8s/pvc.yaml, k8s/cronjob.yaml

Implementation Steps:

• Write a 3-stage Dockerfile (frontend build, backend build, alpine + sqlite runtime).
• Write pvc.yaml for SQLite persistent storage.
• Write deployment.yaml, service.yaml, and ingress.yaml (tutor.puchstein.dev).
• Write cronjob.yaml running at 3 AM daily, executing sqlite3 /data/attendance.db "VACUUM INTO '/data/backup-$(date +%F).sqlite'" and pruning files older than 7 days.

---

Verification Strategy

1. Unit Tests: Execute cargo test in backend/ to verify all new endpoints (Tasks 9-11).
2. End-to-End Test: Start make dev and manually verify all critical paths: tutor login, session/slot creation, student check-in with cookie persistence, FCFS seat collision handling, manual attendance, and exporting.
3. Deployment Test: Run make compose-up to ensure the built Docker container operates as expected, serving Svelte SPA fallback via Axum properly.