# plon/illinispots architecture

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

- Interactive diagram: https://gitdiagram.com/plon/illinispots
- Repository: https://github.com/plon/illinispots

## Overview

##### Frontend Layer
- Interactive Map Component (MapLibre GL JS)
- Building Status Components
- Library Room Components
- UI Components (shadcn/ui)

##### API Layer
- Buildings Availability Endpoint
- Libraries Availability Endpoint
- Connection to both frontend and database layers

##### Database Layer
- Core Tables (from schema/tables.sql)
- Custom Functions (get_current_building_status)
- Data models for buildings, rooms, schedules

##### Data Pipeline System
- Scrapers (Course Explorer, LibCal, Tableau)
- Data Processors
- Building Data Enrichment
- Scheduled tasks (cron jobs)

##### External Data Sources
- Course Explorer
- Facility Scheduling
- Library Reservation System
- Tableau Daily Events

Key Relationships to Highlight:

- External Sources → Data Pipeline
- Data Pipeline → PostgreSQL Database
- Database → API Routes
- API Routes → Frontend Components

##### Real-time Updates
- Periodic data refresh cycles
- Websocket connections if applicable

- Blue: Frontend components
- Green: API layer
- Yellow: Database components
- Orange: Data pipeline
- Grey: External systems

Special Considerations:

##### Core Algorithm Visualization
- State Detection
- Gap Analysis
- Duration Calculation

##### Library System Pipeline
- Three-stage pipeline:
- Room Data Extraction
- Reservation Status Collection
- Availability Processing

Important Elements to Include:

##### Technology Labels
- Next.js/React
- TypeScript
- PostgreSQL
- MapLibre GL JS
- Python (for data pipeline)

##### Data Flow Timing
- Real-time API calls
- Scheduled data updates
- Cron job frequencies

##### Security Layer
- Supabase authentication
- API route protection
- Environment variables

##### Scalability Points
- Database optimization
- Caching strategies
- Load balancing considerations

- Component types (Frontend, Backend, Database, External)
- Status indicators (Available/Occupied)

Level of Detail:

- High-level: Show main system components and their interactions
- Mid-level: Include key subcomponents and data flows
- Low-level: Add specific implementation details for critical features

Remember to include version information and any relevant deployment architecture details if applicable.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        NextFrontend["Next.js Frontend"]
        MapComponent["Map Component"]:::frontend
        LibraryRoom["Library Room Interface"]:::frontend
        UIComponents["UI Components"]:::frontend
        MainPage["Main Page"]:::frontend
        TypeDefs["Type Definitions"]:::frontend
        LibHoursUtil["Library Hours Utility"]:::frontend
        
        NextFrontend --> MapComponent
        NextFrontend --> LibraryRoom
        NextFrontend --> UIComponents
        NextFrontend --> MainPage
        MainPage --> TypeDefs
        MainPage --> LibHoursUtil
    end

    subgraph API
        BuildingsAPI["Buildings Availability API"]:::api
        LibrariesAPI["Libraries Availability API"]:::api
    end

    subgraph Database
        PostgreSQL[(PostgreSQL/Supabase)]:::db
        DBSchema["Database Schema"]:::db
        DBFunctions["Database Functions"]:::db
        
        PostgreSQL --> DBSchema
        PostgreSQL --> DBFunctions
    end

    subgraph "Data Pipeline"
        Pipeline["Data Pipeline Core"]:::pipeline
        TableauScraper["Tableau Scraper"]:::pipeline
        BuildingProcessor["Building Data Processor"]:::pipeline
        DataModels["Data Models"]:::pipeline
        DBLoader["Database Loader"]:::pipeline
        BuildingHours["Building Hours Processor"]:::pipeline
        
        Pipeline --> TableauScraper
        Pipeline --> BuildingProcessor
        Pipeline --> DataModels
        Pipeline --> DBLoader
        Pipeline --> BuildingHours
    end

    subgraph "External Sources"
        CourseExplorer["Course Explorer"]:::external
        FacilityScheduling["Facility Scheduling"]:::external
        LibraryReservation["Library Reservation"]:::external
        TableauEvents["Tableau Daily Events"]:::external
    end

    %% Data Flow
    ExternalSources --> Pipeline
    Pipeline --> PostgreSQL
    PostgreSQL --> BuildingsAPI
    PostgreSQL --> LibrariesAPI
    BuildingsAPI --> NextFrontend
    LibrariesAPI --> NextFrontend

    %% Click Events
    click MapComponent "https://github.com/plon/illinispots/blob/main/components/map.tsx"
    click LibraryRoom "https://github.com/plon/illinispots/blob/main/components/LibraryRoomAvailability.tsx"
    click UIComponents "https://github.com/plon/illinispots/tree/main/components/ui/"
    click BuildingsAPI "https://github.com/plon/illinispots/blob/main/app/api/buildings-availability/route.ts"
    click LibrariesAPI "https://github.com/plon/illinispots/blob/main/app/api/libraries-availability/route.ts"
    click DBSchema "https://github.com/plon/illinispots/blob/main/database/schema/tables.sql"
    click DBFunctions "https://github.com/plon/illinispots/blob/main/database/functions/get_current_building_status.sql"
    click Pipeline "https://github.com/plon/illinispots/tree/main/data-pipeline/"
    click TableauScraper "https://github.com/plon/illinispots/blob/main/data-pipeline/cron/tableau_dailyevents_scraper.py"
    click BuildingProcessor "https://github.com/plon/illinispots/blob/main/data-pipeline/addbuildingcoordinates.py"
    click DataModels "https://github.com/plon/illinispots/blob/main/data-pipeline/models.py"
    click DBLoader "https://github.com/plon/illinispots/blob/main/data-pipeline/load_to_postgres.py"
    click BuildingHours "https://github.com/plon/illinispots/blob/main/data-pipeline/addbuildinghours.py"
    click LibHoursUtil "https://github.com/plon/illinispots/blob/main/utils/libraryHours.ts"
    click MainPage "https://github.com/plon/illinispots/blob/main/app/page.tsx"
    click TypeDefs "https://github.com/plon/illinispots/blob/main/types/index.ts"

    %% Styling
    classDef frontend fill:#3498db,stroke:#2980b9,color:white
    classDef api fill:#2ecc71,stroke:#27ae60,color:white
    classDef db fill:#f1c40f,stroke:#f39c12,color:black
    classDef pipeline fill:#e67e22,stroke:#d35400,color:white
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:white

    %% Legend
    subgraph Legend
        Frontend_L["Frontend"]:::frontend
        API_L["API"]:::api
        Database_L["Database"]:::db
        Pipeline_L["Pipeline"]:::pipeline
        External_L["External"]:::external
    end
```
