How rgodha24/attendance works
Project Type & Purpose
• The project is a full-stack attendance tracking system. It combines a serverless AWS backend, a web dashboard for teachers, and a Rust-based command line tool (running on a Raspberry Pi with a barcode scanner) for collecting student sign-ins.
• The README also points out important security considerations around teacher authentication and data isolation, with a focus on real-time updates and a “local first” web dashboard design (using IndexedDB).
Analyzing the File Structure
• Top-level directories include:
– “packages/core”: Contains core business logic such as database interactions and message handling (modules like “db”, “message”, etc.).
– “packages/functions”: Houses AWS Lambda functions (e.g. auth, scannerPing, ws) presumably responsible for backend functions, REST/trpc APIs, and websocket communication.
– “packages/trpc”: Contains API router code and routers (such as “class”, “scanner”, “signins”) used for exposing backend endpoints via trpc.
– “packages/web”: Contains all the web client assets, including React components, routing, styles, and configuration files for building the dashboard.
– “scanner_code”: Contains the Rust-based CLI program that runs on the Raspberry Pi, handling barcode scanning and communication with the backend.
– “stacks”: Contains infrastructure definitions (API, DB, WS, Sites, Config) likely using SST for deploying and configuring AWS resources.
• Other files (like sst.config.ts, package.json at the root, etc.) tie these pieces together, indicating an integrated workspace managed via pnpm and SST (serverless stack).
Key Components and Their Interactions
a. Main Components:
– Web Dashboard (Frontend): In “packages/web”; communicates with the backend using websockets and API calls.
– AWS Backend (Serverless Functions): In “packages/functions” and “packages/trpc”, provides endpoints for authentication, sign-in processing, and real-time updates.
– Core Logic Layer: In “packages/core”, which handles business logic, database interactions (presumably interfacing with AWS DynamoDB), and message processing.
– Barcode Scanner Client (Rust CLI): In “scanner_code”, running on a Raspberry Pi to capture student sign-ins and upload them to the backend.
– AWS Infrastructure: Defined in “stacks” and managed via SST, including resources such as Lambda functions, DynamoDB tables, Websocket APIs, and possibly API Gateways.
– Authentication & Security: Based on teacher sign-in (with Brophy Google accounts) and room claiming logic to restrict data access.
b. Relationships & Data Flow:
– The barcode scanner sends sign-in data from the Rust CLI tool to the AWS Lambda backend.
– Serverless functions in “packages/functions” process and route requests among the trpc routers, and the “packages/core” module processes database interactions.
– The web dashboard communicates with the Lambda backend via websockets and API calls to fetch the latest sign-in data, storing a local copy in IndexedDB for “local first” performance.
– The infrastructure defined in “stacks” orchestrates and configures these AWS resources.
– The overall security model ensures that teacher credentials (and their unique identifiers) are used as primary keys for accessing sign-in data.
Design Principles & Architectural Patterns
• Modular structure: Separating concerns into distinct packages (core, functions, trpc, web) lends itself to a microservices/multi-package monorepo pattern.
• Serverless architecture: Leveraging AWS Lambda, DynamoDB, and WebSocket-based communication managed via SST.
• Client-server separation: Clear boundaries exist between the frontend dashboard, the serverless backend API, the business logic, and the physical scanner client.
Elements
– Data flow from “Rust CLI Scanner” to “AWS Functions” to “Core Module/DB”.
– Data flow from “AWS Functions” to “Web Dashboard” for real-time updates.
• Grouping the components logically:
– A “frontend” group (packages/web),
– A “backend” group (packages/functions and packages/trpc, and indirectly packages/core),
– “Infrastructure” (stacks and sst.config.ts),
– “Edge/CLI” (scanner_code).
• Use annotations or legends to mark which parts are deployed on AWS and which are client-side (or running on a Raspberry Pi).