# rgodha24/attendance architecture

> Architecture diagram of the GitHub repository rgodha24/attendance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rgodha24/attendance
- Repository: https://github.com/rgodha24/attendance

## Overview

##### 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).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Edge/CLI Layer
    subgraph "Edge/CLI"
        CLI("Rust CLI – Barcode Scanner"):::edge
    end

    %% Backend Layer
    subgraph "Backend"
        LAMBDA("AWS Lambda – Functions"):::backend
        TRPC("trpc API Routers"):::backend
        CORE("Core Business Logic & Database"):::backend
    end

    %% Frontend Layer
    subgraph "Frontend"
        WEB("Web Dashboard"):::frontend
    end

    %% AWS Infrastructure Layer
    subgraph "AWS Infrastructure"
        INF("AWS Infrastructure"):::infra
        SSCFG("SST Config"):::infra
    end

    %% Data Flow
    CLI -->|"sendsSignInData"| LAMBDA
    LAMBDA -->|"routesRequest"| TRPC
    LAMBDA -->|"processesLogic"| CORE
    WEB -->|"API/WebSocketCalls"| LAMBDA
    LAMBDA -->|"pushesUpdates"| WEB
    INF -->|"managesLambda"| LAMBDA
    INF -->|"managesTRPC"| TRPC
    INF -->|"managesCore"| CORE
    SSCFG -->|"configuresInfra"| INF

    %% Click Events
    click WEB "https://github.com/rgodha24/attendance/tree/main/packages/web"
    click LAMBDA "https://github.com/rgodha24/attendance/tree/main/packages/functions"
    click TRPC "https://github.com/rgodha24/attendance/tree/main/packages/trpc"
    click CORE "https://github.com/rgodha24/attendance/tree/main/packages/core"
    click CLI "https://github.com/rgodha24/attendance/tree/main/scanner_code"
    click INF "https://github.com/rgodha24/attendance/tree/main/stacks"
    click SSCFG "https://github.com/rgodha24/attendance/blob/main/sst.config.ts"

    %% Styles
    classDef frontend fill:#A3BE8C,stroke:#000,stroke-width:1px;
    classDef backend fill:#F7C59F,stroke:#000,stroke-width:1px;
    classDef edge fill:#EBCB8B,stroke:#000,stroke-width:1px;
    classDef infra fill:#88C0D0,stroke:#000,stroke-width:1px;
```
