docs/technical_guide.md

Technical Guide

Architecture

• API Gateway orchestrates Detection, Embedding, and Vector Search services.
• Detection and Embedding services load local ONNX models when available.
• Vector Search maintains in-memory cosine index with durable JSON snapshots.
• Gateway stores identity metadata in local SQLite DB for air-gapped persistence.

Offline Runtime Modes

1. Model Runtime Mode: ONNX runtime active with local model files.
2. Deterministic Fallback Mode: Service stays functional for integration and validation if runtime/model binaries are absent.

Dependency Management in Air-Gapped Environments

• Build offline wheelhouse on an internet-enabled machine:
  • ./scripts/build_wheelhouse_online.sh
• Transfer vendor/wheels/ into the air-gapped environment.
• Install dependencies without internet:
  • ./scripts/install_deps_offline.sh

Security

• JWT authentication for protected API endpoints.
• AES-256-GCM encryption helpers for sensitive payload workflows.
• TLS termination can be added at reverse proxy/ingress layer.

Storage

• Metadata: artifacts/metadata/identities.db
• Vector index: artifacts/vector_index/index.json
• Optional enterprise stores: PostgreSQL, MinIO, external vector DB.