# lame-o/ucsd-sitin architecture

> Architecture diagram of the GitHub repository lame-o/ucsd-sitin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lame-o/ucsd-sitin
- Repository: https://github.com/lame-o/ucsd-sitin

## Overview

##### Project Type & Purpose
- This is a full-stack web application built with Next.js and TypeScript. Its purpose is to provide real-time tracking of lecture availabilities, allowing students to see live updates, seat availability, course details, and more.
- Key indicators include its use of Next.js (the app directory, API endpoints, layout, page components) and its dependence on Airtable for course information.

##### High-Level Components
a. Frontend Client:
- Browser/User Interface: The main user interaction point.
- Next.js pages/components (located in the "app" and "components" directories) such as:
- Layout (app/layout.tsx)
- Global styling (app/globals.css)
- Specific UI components like Chat, CourseTooltip, LectureList, Loader, Sidebar, and WordRotate (in the "components" folder).
- Chat Context (app/contexts/ChatContext.tsx) for managing chat state in parts of the UI.

b. API Layer:
- API endpoint for Chat (app/api/chat/route.ts) as part of the backend layer managed by Next.js.
- This layer will handle data passing between the frontend and any external data providers or services.

c. External Data Source:
- Airtable is used to store and manage course, lecture, and seat availability information. This integration is managed by functions in "utils/airtable.ts" which likely fetch and cache data from Airtable.

d. Utility and Helper Functions:
- Additional functions and utilities found in "lib/utils.ts" and "utils/time.ts" provide helper logic for various tasks like time calculations, caching, or transformation of data.

##### Relationships & Data Flow
- The user accesses the application through a browser, interacting with UI components rendered by Next.js.
- Data flows from Airtable (external storage) into the application via utility functions. This data is used to display course and lecture information.
- The API endpoint (chat route) serves specific functionalities like real-time chat features.
- The React Context (ChatContext) manages the state related to chat, ensuring data is consistent across components.
- Real-time updates are handled on the client side via periodic checks and client-side filtering, ensuring that the UI reflects the latest lecture status.

##### Detailed Architectural Elements
- That the frontend is built on Next.js 13 and uses the new “app” directory – emphasizing file-based routing, layout, and page composition.
- Separation between the UI and the API layer; even though they exist in the same repository, they represent distinct responsibilities.
- Demonstrate the real-time update mechanism by indicating timed data refreshes (every minute) flowing from the Airtable data source into the UI.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Browser("Browser/User"):::browser

    subgraph "Next.js Frontend"
        Pages("Next.js Pages & Global Styles"):::frontend
        UIComp("UI Components"):::frontend
        ChatCtx("Chat Context"):::frontend
    end

    API("Chat API Endpoint"):::api
    Airtable("Airtable Integration"):::external
    Utility("Utility Functions"):::utility

    Browser -->|"access"| Pages
    Pages -->|"renders"| UIComp
    Browser -->|"initiatesChat"| API
    API -->|"updates"| ChatCtx
    ChatCtx -->|"feeds"| UIComp
    Airtable -->|"dataFetch"| Utility
    Utility -->|"processesData"| Pages

    %% Click Events for Next.js Pages & Global Styles
    click Pages "https://github.com/lame-o/ucsd-sitin/blob/main/app/page.tsx"
    click Pages "https://github.com/lame-o/ucsd-sitin/blob/main/app/layout.tsx"
    click Pages "https://github.com/lame-o/ucsd-sitin/blob/main/app/globals.css"

    %% Click Events for UI Components
    click UIComp "https://github.com/lame-o/ucsd-sitin/blob/main/components/Chat.tsx"
    click UIComp "https://github.com/lame-o/ucsd-sitin/blob/main/components/CourseTooltip.tsx"
    click UIComp "https://github.com/lame-o/ucsd-sitin/blob/main/components/LectureList.tsx"
    click UIComp "https://github.com/lame-o/ucsd-sitin/blob/main/components/Loader.tsx"
    click UIComp "https://github.com/lame-o/ucsd-sitin/blob/main/components/Sidebar.tsx"
    click UIComp "https://github.com/lame-o/ucsd-sitin/blob/main/components/WordRotate.tsx"

    %% Click Event for Chat Context
    click ChatCtx "https://github.com/lame-o/ucsd-sitin/blob/main/app/contexts/ChatContext.tsx"

    %% Click Event for API Endpoint
    click API "https://github.com/lame-o/ucsd-sitin/blob/main/app/api/chat/route.ts"

    %% Click Events for Utility Functions
    click Utility "https://github.com/lame-o/ucsd-sitin/blob/main/lib/utils.ts"
    click Utility "https://github.com/lame-o/ucsd-sitin/blob/main/utils/time.ts"

    %% Click Event for Airtable Integration
    click Airtable "https://github.com/lame-o/ucsd-sitin/blob/main/utils/airtable.ts"

    %% Styles
    classDef browser fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef frontend fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef api fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
    classDef utility fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
```
