nuk-ai

A real-time Snell library occupancy monitoring and prediction platform that leverages simulated IoT sensor data, machine learning, and conversational AI to provide intelligent insights about space availability at Snell Library.

Overview

nuk-ai transforms how students interact with library spaces by providing real-time occupancy data, predictive analytics, and an intelligent chat interface.

Note

While the core architecture and capabilities are production-ready, the current implementation uses simulated sensor data for demonstration purposes. This approach is inspired by real-world implementations like UCL's occupancy detection system and validated room occupancy datasets.

Technical Architecture

graph TB
    subgraph "Frontend (Next.js)"
        UI[User Interface]
    end

    subgraph "External Services"
       Sensor_Data[Sensor Readings]
    end

    subgraph "Backend (FastAPI)"
        API_Router[API Router]
        Occupancy_Service[Occupancy Service]
        Chat_Service[Chat Service]
        Prediction_Model[ML Prediction Model]
    end
    
    subgraph "Data Layer"
        Supabase[(Supabase Database)]
        Model_Storage[Model Storage]
    end
    
    subgraph "External Services"
        Gemini[Gemini AI Model]
    end
    
    UI -->  API_Router
    API_Router --> Occupancy_Service
    API_Router --> Chat_Service
    Chat_Service --> Gemini
    Chat_Service --> Prediction_Model
    Occupancy_Service --> Supabase
    Prediction_Model --> Model_Storage
    Prediction_Model --> Supabase
    Sensor_Data --> Supabase

Loading

Tech Stack

Frontend

• Next.js App Router for modern routing patterns
• Tailwind CSS v4 Utility-first CSS framework
• Radix UI Components Accessible, unstyled UI primitives with ARIA compliance and keyboard navigation

Backend

• FastAPI Modern Python web framework with type validation and async support
• Supabase (PostgreSQL) Managed infrastructure

Machine Learning

• Prophet (Meta) Time series forecasting with minimal hyperparameter tuning required
• Google Gemini API Natural language understanding and tool integration capabilities

Infrastructure

• Render Cloud platform hosting both backend and frontend
  • Single FastAPI server serving both API endpoints and static Next.js frontend
  • Web service automatically builds from GitHub repository
  • Scheduled cron job for sensor data simulation every 5 minutes

Deployment Architecture

The application is deployed as a unified service on Render with the following components:

1. FastAPI Backend

   • Serves API endpoints at /api/* for occupancy data and chat functionality
   • Runs on Python 3.11 with dependencies specified in backend/requirements.txt
   • Connects to Supabase for data storage and retrieval

2. Next.js Frontend

   • Built as a static export and served by the FastAPI application
   • Frontend assets are served at /_next path
   • The main application is served at the root path /

3. Data Simulation

   • Scheduled cron job executes backend/scripts/generate_data.py every 5 minutes
   • Simulates IoT sensor data based on time-of-day occupancy patterns
   • Inserts generated readings directly into Supabase

4. Unified Deployment

   • Single service handles both API requests and serves the frontend
   • Environment variables configured in Render's dashboard
   • Automatic deployments triggered by pushes to the main branch

Database Schema

The system uses a hierarchical structure to organize data.

• floors: Library floor definitions (4 floors)
• zones: Spatial divisions within floors (9 zones per floor in 3x3 grid)
• sensors: Individual IoT devices (~16-17 sensors per zone)
• sensor_readings: Time-series data (timestamp, sensor_id, status, temperature)

Core Features

Real-time Occupancy Monitoring

The platform tracks library occupancy through SIMULATED temperature-based IoT sensors detecting human presence (30-35°C for occupied seats vs 20-21°C ambient). Data is pushed to the database every 5 minutes courtesy of a cron job.

Machine Learning Predictions

The system aggregates historical sensor readings to train Prophet models that forecast future occupancy patterns. These trained models are serialized and stored in Supabase Storage, where they're dynamically loaded to serve real-time predictions through the FastAPI endpoints whenever users query future availability.

Conversational AI Interface

The conversational interface processes natural language queries about library availability, intelligently integrating real-time occupancy data with contextual information. The system generates visual heatmaps directly within chat responses to illustrate floor-by-floor occupancy patterns.

Visual Analytics

• Heatmap Visualizations

  • Color-coded occupancy levels using an intuitive green-to-red gradient where green indicates low density and red shows high occupancy zones 3x3 grid layout that directly mirrors the physical floor plan, enabling students to quickly identify their target zone location
  • Real-time updates that refresh automatically as new sensor data arrives every 5 minutes
  • Interactive navigation allowing users to click between floors and expand views for detailed zone-level information

• Capacity Metrics:

  • Overall library utilization percentage displayed prominently to show general availability at a glance
  • Floor-by-floor breakdowns providing granular capacity data for students with specific floor preferences
  • Responsive design ensuring consistent functionality across desktop, tablet, and mobile devices for on-the-go checking

Data Simulation

The backend/scripts/generate_data.py script creates realistic data as will be generated by an IoT device. The device in question will be placed beneath every table and detect temperature changes due to the presence/absence of people.

cd backend
python scripts/generate_data.py  # Runs a single simulation cycle

Development & Deployment Guide

Local Development

1. Backend Setup:

   cd backend
   ./setup.sh  # Creates virtual environment and installs dependencies
   source venv/bin/activate
   python main.py  # Starts the FastAPI server at http://localhost:8000

2. Client Development:

   cd client
   npm install
   npm run dev  # Starts Next.js dev server at http://localhost:3000

Deployment Architecture

The application uses a unified deployment model on Render:

1. Automated Data Generation:

   • A Render cron job executes python backend/scripts/generate_data.py every 5 minutes
   • This simulates IoT sensor readings and inserts them into Supabase
   • The occupancy probability varies based on time-of-day and day-of-week patterns

2. CI/CD Pipeline:

   • Pushing to the main branch triggers automatic deployment on Render
   • Build process:
     1. Installs Python dependencies from backend/requirements.txt
     2. Installs Node.js and npm packages from client/package.json
     3. Builds the Next.js frontend
     4. Starts the FastAPI server which serves both API endpoints and frontend

Environment Configuration

Required environment variables for deployment:

• SUPABASE_URL: Supabase project URL
• SUPABASE_KEY: Supabase service role API key
• GEMINI_API_KEY: Google Gemini API key for chat functionality
• DATABASE_URL: PostgreSQL connection string (if using direct DB access)

Future Enhancements

• LSTM networks for complex temporal patterns
• Student ID card system connection
• Library catalog synchronization
• Push notifications for space availability
• Location-based services for other halls/spaces

---

Built by Parthiv Menon, Jovin Nicholas, Aditya Ayyappan for Hack NUACM 2025.