81 lines
4.0 KiB
Markdown
81 lines
4.0 KiB
Markdown
# 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.
|
|
|
|
<!-- SLM-START -->
|
|
## 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`.
|
|
<!-- SLM-END -->
|
|
|
|
## Project Overview
|
|
|
|
- **Architecture**: Standalone repo 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 & pnpm
|
|
- SQLite
|
|
|
|
### Demo Credentials
|
|
- **Admin**: `admin@tutortool.com` / `admin`
|
|
|
|
### Environment-specific Fixes
|
|
- **btrfs pnpm fix**: Use `--package-import-method copy` when running pnpm.
|
|
|
|
### 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`).
|
|
- `pnpm 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/admin/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.
|