IntelliKeep Gateway Documentation

The IntelliKeep Gateway serves as the central backend repository, API coordinator, and alert processing hub for the **IntelliKeep Smart Tag system**. It records active tag heartbeats, tracks battery metrics, monitors signal indicators (RSSI), and forwards warning alerts via Firebase Admin Cloud Messaging (FCM).

System Architecture

The IntelliKeep backend is structured into distinct layers:

• API Handlers (Flask): Recovers JSON payloads sent by hardware tags, updates notes databases, and processes administrative dashboards.
• FCM Alert Dispatcher: Interacts with Firebase Admin SDK to push instant alert payloads to registered mobile device tokens.
• Worker Thread (Missing Checker): A lightweight, asynchronous task runner that runs in the background to detect tags that have missed their expected check-in interval.
• Calendar Bridge: Keeps a historical log of events and tasks inside Google Calendar for quick developer audits.

Virtual Environment & Setup

The gateway is written in Python using Flask and SQLAlchemy. Follow these steps to set up the workspace locally:

# 1. Clone or navigate to the directory
cd /home/nelsonserver/websites/intellikeep

# 2. Set up virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install required libraries
pip install -r requirements.txt

Key Dependencies (`requirements.txt`):

Database & Schema Setup

The database uses SQLite (`intellikeep.db`). The SQL schema definitions are split into distinct sql files for developer clarity:

• `database_schema.sql`: Base schema definitions for tables, tags, users, logs, and settings.
• `database_schema_admin.sql`: Table overrides and structures for TOTP and security records.
• `database_schema_user.sql`: User profiles and customization data.

To initialize the SQLite database from your SQL schema files, run:

# Initialize database
sqlite3 intellikeep.db < database_schema.sql
sqlite3 intellikeep.db < database_schema_admin.sql
sqlite3 intellikeep.db < database_schema_user.sql

Environment Configuration (.env)

System timing parameters and credentials should be configured in your `.env` file:

# SMTP settings
SMTP_HOST=mail.yourdomain.net
SMTP_PORT=587
SMTP_USER=your_user@yourdomain.net
SMTP_PASSWORD=your_secure_password

# Temporal Guards for Jitter Debouncing
OUT_OF_RANGE_DEBOUNCE_SECONDS=30
MISSING_DEBOUNCE_SECONDS=120

# Google Calendar Configuration
CALENDAR_ID=your_email@gmail.com

Firebase FCM Alert Configuration

Tamper and out-of-range alarm payloads are pushed to Android/iOS devices via Firebase. Follow these configuration requirements:

Google Calendar Sync

Active tags can log their audit history and trigger tasks inside Google Calendar. Save your client credential file (downloaded from the Google Cloud Console) as `google-admin.json` in the project directory.

TOTP Security Configuration

Administrative modifications (like clearing tags, changing timing boundaries, or resetting logs) are protected via Time-based One-Time Passwords (TOTP).

To access admin features, you must use a standard authenticator app (such as Google Authenticator) and register the administrative key located in your database.

Out of Range & Jitter Debouncing

Transient RF signal drops (jitter) can cause a beacon to look temporarily disconnected. To prevent false alarms, the backend uses a temporal debouncer: