HOMEPOT Client Documentation¶

Welcome to the HOMEPOT Client documentation! This comprehensive guide will help you get started with the HOMEPOT IoT device management platform.

For New Users¶

Getting Started - First time setup
Running Locally - How to run the application
Integration Guide - Complete setup and usage guide

For Developers¶

Engineering TODO - Task list with priorities
Development Guide - How to contribute
Testing Guide - How to test your code
API Testing Guide - Manual API testing and validation

For Stakeholders¶

Visual Examples - Screenshots and diagrams
Audit & Compliance - Enterprise logging and compliance

Recent Documentation Updates (November 2025)¶

NEW: AI Integration Roadmap¶

Strategic 9-month plan - Complete roadmap from current website integration to AI-powered data analysis platform with anomaly detection, predictive maintenance, and natural language queries.

Read AI Roadmap → | Executive Summary → | Anomaly Detection →

Device Metrics Collection¶

Comprehensive metrics API - Monitor device health with system resources (CPU, memory, disk), application metrics (transactions, errors), and network stats. Includes testing simulator and Python implementation examples.

Read Device Metrics Guide →

Integration Guide¶

2000+ lines - Your complete technical reference covering architecture, installation, API reference, frontend guide, push notifications (all 5 platforms), testing, deployment, and troubleshooting.

Read Integration Guide →

Engineering TODO¶

1500+ lines - Clear, actionable task list with phase-by-phase breakdown, priorities, estimates, acceptance criteria, and quick reference commands.

Read Engineering TODO →

PostgreSQL Migration¶

Complete migration from SQLite to PostgreSQL - Production-ready database with async performance, proper timezone handling, and enterprise features.

Read PostgreSQL Migration Guide →

Quick Start¶

# ONE COMMAND to run everything:
./scripts/start-website.sh
# Access:
# Frontend: http://localhost:5173
# Backend: http://localhost:8000
# API Docs: http://localhost:8000/docs

Feature Guides¶

Explore HOMEPOT's capabilities:

POS Management - Manage sites, devices, and jobs
Real-time Dashboard - Live monitoring and WebSocket features
Agent Simulation - POS terminal simulation and management
Audit & Compliance - Enterprise logging and reporting

Technical Documentation¶

For developers and system administrators:

Development Guide - Testing, code quality, and contributing
Database Guide - Database setup, management, and usage

Platform Integration Guides¶

Push notification integrations for different platforms:

Push Notification System - Overview and architecture
Firebase Cloud Messaging (FCM) - Android/Linux device push notifications
Windows Notification Service (WNS) - Windows device push notifications
Apple Push Notification service (APNs) - iOS/macOS/watchOS/tvOS device push notifications

System Overview¶

HOMEPOT is a complete four-phase enterprise POS management system:

Phase 1: Core Infrastructure¶

PostgreSQL database with comprehensive models
Complete CRUD operations for sites, devices, jobs, and users
Robust error handling and transaction management

Phase 2: Enhanced API & Dashboard¶

FastAPI application with automatic documentation
WebSocket-powered real-time dashboard
Interactive monitoring interface

Phase 3: Agent Simulation¶

23+ realistic POS terminal simulators
State machine-driven behavior (Idle → Updating → Health Check)
Realistic hardware metrics and error simulation

Phase 4: Audit & Compliance¶

Enterprise-grade audit logging (20+ event types)
Compliance-ready event tracking
Real-time audit statistics and reporting

What's Included¶

Out of the box, HOMEPOT provides:

14 Pre-configured Sites (restaurants, retail stores)
23+ Active POS Agents (realistic terminal simulation)
Real-time Dashboard (live monitoring with WebSocket updates)
Enterprise Audit Logging (compliance-ready event tracking)
Complete REST API (comprehensive device management)
Interactive Documentation (Swagger/OpenAPI interface)

Getting Help¶

GitHub Issues - Bug reports and feature requests
Collaboration Guide - Development and contribution guidelines
Development Guide - Testing and code quality

Architecture¶

┌─────────────────────────────────────────────────────────────────┐
                 HOMEPOT POS Management Dashboard                 
                      (Real-time Monitoring)                       
├─────────────────────────────────────────────────────────────────┤
   ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  
       Live Site            POS Agent            Audit Trail       
       Monitoring           Simulation            & Reports        
       (WebSocket)          (23+ agents)         (Compliance)     
   └─────────────────┘  └─────────────────┘  └─────────────────┘  
├─────────────────────────────────────────────────────────────────┤
                       FastAPI REST API                           
                (Sites, Devices, Jobs, Audit)                     
├─────────────────────────────────────────────────────────────────┤
                      Database Layer                              
           (Sites, Devices, Jobs, Users, Audit Logs)             
└─────────────────────────────────────────────────────────────────┘

Ready to get started? Begin with the Getting Started Guide for a 5-minute setup.