👁️ HORUS KEY: Sovereign Digital Travel & FinTech Ecosystem

A State-of-the-Art (SOTA) Sovereign Modular Monolith for Cryptographic Identity, Border Logic, and Tourism Fintech

---

📋 Executive Overview

HORUS KEY is an enterprise-grade "Modular Monolith" platform engineered to unify border management, tourist identity, digital ticketing, and transit fintech. Designed for zero-trust security and data sovereignty, Horus replaces fragmented paper workflows with an immutable, single-source-of-truth ecosystem.

Key Innovations:

• Decoupled Logic Engines: Policy enforcement (Visa Rules, Dynamic Pricing, Currency Multipliers) is completely decoupled from the presentation layer to ensure immutable rule application.
• Biometric Zero-Knowledge Hashing: Facial features are converted directly to non-reversible SHA-512 hashes—raw biometric images are never stored or transmitted.
• Smart AI Key Rotation: Integrated Multimodal AI (Google Gemini 3.6 Flash) equipped with automated round-robin key rotation, rate-limit resilience, and context awareness.
• Integrated Fintech & Reverse QR: Transforms any device into a secure point-of-sale terminal for instant transit, monument ticketing, and merchant transactions.

---

🏗️ System Architecture

HORUS operates as a Sovereign Single-File Architecture (horus.py), maximizing auditability, deployment velocity, and cross-platform portability (Linux, Windows, Docker, Google Colab).

graph TD
    User[Traveler / Agency] -->|Biometric Scan| Security[HorusSecurity Layer]
    Security -->|SHA-512 Hash| DB[(HorusDB Sovereign Storage)]
    
    subgraph "Core Logic Engines"
        Visa[VisaPolicy Engine]
        Price[PriceCalculator Engine]
        Eco[EcoGamification Engine]
        AI_Rotator[Gemini AI Key Rotator]
    end
    
    subgraph "Service & Fintech Modules"
        Wallet[Fintech / Digital Wallet]
        Transport[Mobility & Transit Gate]
        Ticketing[Heritage / Monument Ticketing]
        PDFGen[ReportLab PDF Passport Generator]
    end
    
    DB <--> Visa
    DB <--> Price
    DB <--> Wallet
    AI_Rotator <-->|Multimodal Intelligence| DB

Loading

---

🛡️ Core Pillars & Capabilities

🛂 I. Cryptographic Biometric Identity

• Algorithm: SHA-512 Hashing with salt.
• Privacy Contract: Zero-Knowledge architecture. Raw camera frames are analyzed in memory and immediately discarded; only the salted hash (BIO-8F4A...) is committed to storage.

💳 II. Sovereign Tourist Wallet & Reverse QR

• Mechanism: Supports $200 USD minimum activation gates (CBE alignment) and instant peer-to-merchant transfers.
• Reverse QR Protocol: Parses encrypted strings (PAY:VENDOR_ID:AMOUNT:CURRENCY) for friction-free transit and retail checkout.

🏛️ III. Multi-Tier Dynamic Group Ticketing

• Dynamic Basket Calculations: Auto-applies discounts for Students (ISIC standard: 50%), Children (30%), and regional Arab/Egyptian subsidies while maintaining price floors.

🤖 IV. Multimodal Gemini 3.6 AI Engine & Fallback Chain

• Load Distribution: Automated load-balancing across key pools (GEMINI_KEYS).
• Multi-Model Fallback Resilience: Automatic, zero-latency model degradation chain if quota or rate-limits are hit: gemini-3.6-flash ➔ gemini-3.5-flash ➔ gemini-3-flash-preview ➔ gemini-2.5-flash

🌿 V. Eco-Gamification Engine

• Green Transit Scoring: Rewards travelers using sustainable transit (Cairo Monorail, LRT, Electric Buses: +20 pts; Metro: +10 pts) with dynamic marketplace discounts.

---

💻 Tech Stack & Dependencies

Component	Technology	Role
Language	Python 3.10+	Core Backend & Logic Processing
Database	Embedded SQLite3	Local Data Sovereignty & Zero Latency
UI Engine	Gradio (v4.0+)	Reactive Mobile & Desktop Interface
AI Processing	Google GenAI SDK	Multimodal Chat & Vision Analysis
Document Engine	ReportLab	Cryptographic PDF Passport & E-Visa Generation
Vision & Scanning	OpenCV & PyZBar	Real-time QR Code & Camera Processing

---

🚀 Quickstart & Deployment

1. Environment Setup

# Clone repository
git clone https://github.com/G3need/HORUS.git
cd HORUS

# Install core dependencies via requirements.txt
pip install -r requirements.txt

2. Configure API Keys

Set your Google Gemini API key(s) in your environment (multiple keys can be comma-separated for automatic load balancing):

# Linux / macOS
export GEMINI_KEYS="AIzaSyYourKey1...,AIzaSyYourKey2..."

# Windows (Command Prompt)
set GEMINI_KEYS=AIzaSyYourKey1...,AIzaSyYourKey2...

# Windows (PowerShell)
$env:GEMINI_KEYS="AIzaSyYourKey1...,AIzaSyYourKey2..."

3. Launch HORUS

python horus.py

Open the generated local URL (e.g. http://127.0.0.1:7860) in your browser.

---

⚖️ Compliance & Legal Framework

1. Egyptian Data Protection Law: Encrypted at rest, zero raw biometric storage.
2. Central Bank of Egypt (CBE) Financial Guidelines: Structured audit logging and transaction non-repudiation.
3. Ministry of Tourism & Antiquities: Hardcoded pricing floors and automated regional subsidy calculation.

---

Architects: Ahmed Geneed + Mohamed Geneed
Copyright Registry Submission – Arab Republic of Egypt (2026)