HikCentral Professional Gateway & Real-Time Analytics Dashboard

An enterprise integration, access control telemetry, and passenger flow occupancy platform built for HikCentral Professional systems. It bridges HikCentral's dual upstream gateways (Artemis OpenAPI and Bumblebee ISAPI), provides live magnetic sensor audits, tracks mall occupancy with adaptive proportional calibration, and exposes interactive Swagger and API explorer interfaces.

---

🌟 Key Capabilities

• 🟢 Real-Time Access Control & Door Telemetry: Observational sensor classification (VERIFIED_SENSOR, SENSORLESS_OPEN, SENSORLESS_JUMPERED), access session lifecycle tracking (CARD_PASS, DOOR_OPEN, DOOR_CLOSE, ALARM_TIMEOUT), and live WebSocket streams.
• 👥 Passenger Flow & Mall Occupancy Engine: Real-time inside headcount computation from camera counting channels, facility-time business cycles with a configurable reset boundary, and daytime transit bleed compensation.
• 📐 Adaptive Proportional Calibration Model: Dynamically learns sensor exit multiplier (k) from nocturnal quiet-hour convergence, featuring an automated quarantine engine (AUTO_EXCLUDED) for abnormal operational cycles.
• 📊 Admin Data Visualizer & Audit Suite: Live time-series analytics, interactive drift charts, historical cycle reconciliation, and high-performance streaming export (CSV/JSON).
• 🔐 Dual Upstream Gateway Architecture:
  • Artemis OpenAPI: HMAC-SHA256 request signing using AppKey/AppSecret over port 9016/443.
  • Bumblebee ISAPI: Encrypted administrative session negotiation (MD5/AES challenge-response) with automated keepalive pings over port 443.
• 📖 Interactive API Documentation & Explorer:
  • FastAPI Swagger UI at /docs
  • ReDoc UI at /redoc
  • HikCentral Dual API Explorer at /api-docs (with 189+ parsed Artemis APIs and Bumblebee catalog)
• 🌐 Dynamic Internationalization (i18n): Instant runtime English/Spanish language toggling across all dashboard views.

---

🚀 Quick Start & Operations

1. Prerequisites

• Python 3.11+ (Python 3.14 compatible)
• SQLite3

2. Automated Host Provisioning (hikctl)

The repository includes hikctl, a unified cross-platform lifecycle supervisor for Linux (systemd) and Windows Server 2019+ (SCM via WinSW v3):

# Linux (Debian / Ubuntu / Systemd)
sudo ./hikctl setup

# Windows Server 2019+ (Elevated PowerShell / CMD)
.\hikctl.cmd setup

The gateway will start on http://localhost:8888 (configurable via APP_PORT).

Tip

Detailed Guides Available:

• Fresh Installations & Legacy Upgrades: See Operational Runbook §10 for step-by-step instructions covering both brand-new servers and migrating existing Windows Scheduled Tasks / run.sh deployments without data loss.
• CLI Command Reference: See Operational Runbook.
• Host Deployment Architecture: See Deployment & Operations Guide.

---

🛠️ Development, Standards & Testing

Development Dependencies & Pre-Commit

# Install development and linting tools
pip install -r requirements-dev.txt

# Install git pre-commit hooks
pre-commit install

Running Linter & Formatter

# Run Ruff linting and formatting check
./scripts/lint.sh

# Or invoke ruff directly
ruff check .
ruff format --check .

Running Test Suite

pytest

---

📂 Documentation & Architecture

Comprehensive documentation is available in the docs/ directory:

• Master Documentation Index
• Code Standards & Architecture Patterns
• Git & Forgejo Workflow
• System Architecture & Topology
• Current Occupancy and Calibration Decision
• Documentation Accuracy and Coverage Audit
• API Architecture & Explorer Guide
• Deployment & Windows Service Guide
• Domain Model & Glossary
• Agent Directives