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.