tutortool/GEMINI.md

TutorTool: Attendance Tracking System

TutorTool is a full-stack web application for tracking student attendance in tutoring sessions. It features a Rust backend and a SvelteKit frontend.

SuperLocalMemory (SLM)

• Mandate: Use SLM for all project-related memories, decisions, and context.
• Workflow:
  • Recall: At the start of every session or when context is missing, use the recall tool with relevant keywords (e.g., tutortool, architecture).
  • Remember: After implementing features, fixing bugs, or establishing new patterns, use the remember tool with appropriate tags.
• Tools: remember, recall, list, get_status.

Project Overview

• Architecture: Monorepo with a Rust backend (Axum) and a SvelteKit 5 frontend.
• Backend:
  • Framework: Axum (async) on Tokio.
  • Database: SQLite via SQLx. Migrations are automatically run at startup.
  • Auth: JWT-based authentication (jsonwebtoken crate) with bcrypt for passwords.
  • Static Serving: Serves the compiled SvelteKit frontend as a Single-Page App (SPA).
• Frontend:
  • Framework: SvelteKit 5 using Svelte Runes ($state, $derived, etc.).
  • Build Tool: Vite.
  • Package Manager: pnpm (preferred over npm).
  • Styling: Vanilla CSS (based on design handoff).
  • API: Centralized fetch wrapper in src/lib/api.ts.

Build and Run

Prerequisites

• Rust 1.95.0 (pinned via rust-toolchain.toml)
• Node.js & npm
• SQLite

Key Commands

• make dev: Starts both backend and frontend in parallel (requires JWT_SECRET and DATABASE_URL in environment).
• make build: Performs a full production build (frontend first, then backend).
• cargo test: Runs all backend unit and integration tests (uses sqlx::test).
• npm run check: Performs TypeScript and Svelte type checking for the frontend.

Environment Variables

• DATABASE_URL: Path to the SQLite database (e.g., sqlite:./dev.db).
• JWT_SECRET: Secret key for signing and verifying JWT tokens.
• STATIC_DIR: Path to the compiled frontend (defaults to ../frontend/build).

Development Conventions

Backend (Rust)

• Error Handling: Uses a custom AppError enum (see error.rs) that implements IntoResponse.
• Database: Queries use runtime sqlx::query() / sqlx::query_as(). Note: While CLAUDE.md mentions compile-time queries might need DATABASE_URL, the current implementation primarily uses runtime queries to simplify CI/CD.
• Routing: Routes are modularized in backend/src/routes/ and merged in routes/mod.rs.
• Auth: Use the TutorClaims extractor in route handlers to enforce authentication and access the current user's ID and email.

Frontend (SvelteKit)

• Runes: Use Svelte 5 Runes for state management.
• Type Safety: Ensure frontend/src/lib/types.ts is kept in sync with backend/src/models.rs.
• Layouts:
  • src/routes/login/: Public login page.
  • src/routes/admin/: Protected admin routes (tutor dashboard).
  • src/routes/s/[code]/: Public student check-in page.

Key Files

• backend/src/main.rs: Entry point and server configuration.
• backend/src/db.rs: Database initialization and migration logic.
• backend/src/auth.rs: JWT encoding/decoding and Axum extractor.
• backend/src/models.rs: Shared data models (DB rows and Request/Response DTOs).
• frontend/src/lib/api.ts: API client for frontend-backend communication.
• frontend/src/lib/RoomCanvas.svelte: Interactive SVG-based room layout component.
• conductor/attendance-tool.md: Detailed implementation plan and project scope.

Project History & Context

• The project was migrated/continued from a feature branch as documented in conductor/attendance-tool.md.
• Deployment is targeted at Kubernetes with a 3-stage Docker build.