thilac01/jpl-iot-middleware

Purpose and Entry Points

JPL Security & IoT Middleware is a FastAPI integration layer between a Koha MySQL replica, RFID/Raspberry Pi security gates, and an operations dashboard. Primary application entry points are main.py (ASGI app, used by Gunicorn) and run.py (local execution). Static dashboard assets are served from static/index.html, static/app.js, and static/style.css.

Application Composition

The FastAPI lifecycle assembles configuration, logging, shared infrastructure, middleware, and API routers. Central application concerns are located in app/core/config.py, app/core/logging.py, and main.py. Runtime request boundaries add correlation IDs, error normalization, and security headers through app/middleware/correlation.py, app/middleware/error_handler.py, and app/middleware/security.py.

HTTP and WebSocket API Boundary

Routers separate externally visible capabilities:

• Circulation reads and Koha-oriented loan/audit views: app/routers/circulation.py.

• Safe database discovery/table inspection: app/routers/tables.py.

• IoT management and gate telemetry: app/routers/iot.py.

• Liveness, readiness, diagnostics, and metrics: app/routers/health.py.

• Persistent real-time client connections: app/routers/ws.py.

Clients enter through HTTP or /ws; routers coordinate services and return API/dashboard-facing data rather than exposing database or device access directly.

Database and Secure Connectivity

Database access is mediated by an asynchronous session/pool layer in app/db/session.py, with SSH-tunnel establishment in app/db/tunnel.py. The primary external data source is a remote Koha MySQL replica, reached via an SSH gateway and local tunnel binding. This boundary isolates credentials, reconnection behavior, and transport security from routers and services. Legacy/top-level database support may also exist in db_utils.py.

Change Data Capture and Real-Time Events

app/services/cdc_engine.py streams MySQL binlog mutations for Koha circulation-related tables, persists binlog position for restart recovery, and produces real-time events. The WebSocket layer in app/routers/ws.py consumes this event stream to push database mutations, checkout alerts, and gate signals to connected dashboards. CDC can trigger alert delivery through app/services/smtp_service.py.

IoT Gate Control Plane

app/services/iot_service.py owns Raspberry Pi gate discovery, registration, heartbeats, TTL/offline supervision, remote agent deployment, command execution, and device metrics. app/routers/iot.py is the controlled ingress for edge-node requests and administrative actions, keeping SSH/network operations behind the service boundary.

Koha Integration and Security

app/services/koha_service.py provides a dedicated integration point for Koha REST interactions, distinct from direct replica reads and CDC. Security policy is centralized in app/core/security.py and applied at request level by app/middleware/security.py; it includes optional API-key enforcement and protections around dynamic SQL/table access.

Deployment and Infrastructure

The service runs on Python/FastAPI, commonly behind Nginx (nginx.conf) for TLS, rate limiting, compression, and WebSocket upgrade handling. Deployment options include containers via Dockerfile, docker-compose.yml, and docker-compose.dev.yml; systemd via jpl-middleware.service; and multi-worker Gunicorn via gunicorn_conf.py. External operational dependencies are SSH, MySQL/Koha binlogs, SMTP, Raspberry Pi nodes, and an Nginx reverse proxy.