> For the complete documentation index, see [llms.txt](https://quantifai.gitbook.io/quantifai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://quantifai.gitbook.io/quantifai/technical-architecture.md).

# Technical Architecture

QuantifAI’s technology stack is engineered for ultra-low latency, fault tolerance, and seamless scalability across all components:

## Data Layer & Ingestion

**Event Backbone (Kafka + Schema Registry)**

* **Throughput/latency targets:** ≥1M msgs/sec aggregate, p99 end‑to‑end ingest < 5–15 ms.
* **Topics:** `ticks.*`, `orderbook.snapshots`, `onchain.tx`, `social.raw`, `signals.*`, `exec.events`, `risk.alerts`.
* **Partitions & keys:** key by `{symbol|chain|venue}` to preserve ordering per instrument/route; stretch partitions for hot symbols.
* **Backpressure:** enable `min.insync.replicas=2`, producer `linger.ms=3–10`, `compression.type=zstd`, consumer `max.poll.records=10k`.
* **Schema evolution:** Avro/Protobuf with **Confluent Schema Registry** enforcing *backward* compatibility; blue/green reader rollout for breaking fields.

```properties
# Producer (ticks)
acks=all
compression.type=zstd
batch.size=262144
linger.ms=5
enable.idempotence=true
max.in.flight.requests.per.connection=1
```

**ETL & Feature Fabric (Airflow + PySpark)**

* **Pipelines:**
  * *Bronze → Silver:* raw → cleansed (dedup, null‑guard, tz normalization).
  * *Silver → Gold:* feature views (embeddings, funding diffs, LP depth curves).
* **Scheduling:** mixed **cron** + **event‑triggered** DAGs (Kafka events, S3 object puts).
* **Idempotency:** task‑level **checksum markers** in Delta transaction logs to avoid double writes.
* **SLAs:** core features hourly p95 < 10 min, intraday features every 1–5 min.

**Storage Tiers**

* **Delta Lake on S3:** versioned fact tables, time travel for reproducible backtests; compact with OPTIMIZE + ZORDER on `(symbol, ts)`.
* **InfluxDB:** high‑rate time‑series (ticks, metrics); retention e.g., hot 30d, warm 365d in S3.
* **Redis:** hot‑path caches for order books, latest signals, rate limits; use **Redis Cluster** + **TLS** + **ACLs**.

## Model Training & Serving

**GPU Fleet (Kubernetes)**

* **Nodes:** NVIDIA **P4/P5** (or L4/H100 as alt) with MIG partitioning for small models; **NodeFeatureDiscovery** + **GPU Operator**.
* **Frameworks:** PyTorch Lightning + **Horovod** for DDP, **NCCL** over RDMA.
* **Data IO:** Petastorm/TFRecords from Delta snapshots; shard by time/symbol.

**Experiment & Reproducibility**

* **MLflow**: params, metrics, artifacts, lineage; register “champion/challenger”.
* **DVC**: pin feature snapshots and training sets; gate merges on hash‑matched inputs.
* **GitOps (Argo CD):** manifests + model versions promoted via PRs; automatic rollback on SLO breach.

**Low‑latency Serving**

* **Triton Inference Server** with **dynamic batching**, **TensorRT** optimizations (FP16/INT8).
* **Budgets:** per‑request p99 < 10 ms on‑box; end‑to‑end (API → score) p99 < 50–80 ms.
* **A/B & canary:** routing weights in Envoy; shadow traffic for “candidate” models.

```yaml
# Triton config (simplified)
name: ts_transformer
backend: tensorrt
max_batch_size: 128
dynamic_batching:
  preferred_batch_size: [8,16,32,64]
  max_queue_delay_microseconds: 2000
instance_group:
  - kind: KIND_GPU
    count: 2
```

## Execution Layer

**Go Microservices (10k TPS target)**

* **Services:** `router`, `signer`, `settlement`, `bridge-orchestrator`, `risk-gateway`.
* **RPC:** batched JSON‑RPC pools per chain (Ethereum, Celo…); failover endpoints + health scoring.
* **Determinism:** request hashing + **idempotency keys**; exactly‑once intent handling via outbox pattern (Kafka).

```go
// Pseudocode: batched RPC with fallback
cli := rpcpool.New([]string{eth1, eth2}, rpcpool.WithQoS())
ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
defer cancel()
resp, err := cli.Batch(ctx, payloads, rpcpool.WithRetry(3))
```

**Cross‑Chain Settlement**

* **Adapters:** LayerZero, Wormhole, Polkadot XCM (abstracted behind a `Bridge` interface).
* **Guarantees:** submit with **proof attestations** + on‑chain receipts; reconcile in `settlement` svc with Merkle root anchors.

**MEV Safety & Execution Tactics**

* **Protection:** submit via **Flashbots / Eden** for private tx; MEV‑boosted relay allowlists.
* **Detection:** mempool simulators score sandwich risk → auto switch to private route.
* **Order slicing:** iceberg, **TWAP/VWAP**, smart split across venues; constraints from **risk-gateway** (slippage caps, venue blacklist).

## API & UI

**API Gateway**

* **Express.js + Apollo GraphQL**, behind Envoy/NGINX; JWT/OAuth2 via Keycloak.
* **Rate limits:** Redis sliding window; per‑tenant + per‑API key + per‑IP.
* **Pagination:** cursor‑based for streams (avoid deep offsets).
* **WebSockets:** GraphQL subscriptions for live signals/exec updates.

```graphql
type Subscription {
  signalStream(symbol: String!): SignalUpdate!
  orderEvents(portfolioId: ID!): OrderEvent!
}
```

**Frontend App (React 18 + TS)**

* **State:** RTK Query / React Query;
* **Charts:** Recharts (signals, exposures), **WASM** backtest previews (Rust → wasm-pack).
* **UX:** multi‑tab workspaces, strategy builder (drag‑n‑drop), correlation/heatmap views.
* **Security:** CSP headers, code‑splitting, Sentry + source maps.

**Developer Tooling**

* **Auto‑generated SDKs** (OpenAPI/GraphQL codegen) for Python & TS; **Go CLI** for headless ops (cron jobs, CI hooks).

## DevOps & Observability

**CI/CD & Release Hygiene**

* **GitLab CI:** build → unit/integration → security scans (SAST/DAST) → e2e → sign images (Sigstore/Cosign).
* **Helm charts** per service; **blue‑green**/**canary** via Argo Rollouts; traffic weights tied to SLOs (error rate/latency).

**Telemetry Stack**

* **Metrics:** Prometheus + Grafana dashboards (SLOs: API p99, router success rate, inference latency).
* **Logs:** ELK (vector/FluentBit → Elasticsearch); structured with trace IDs.
* **Tracing:** OpenTelemetry → Jaeger; end‑to‑end spans from UI → API → router → chain node.
* **Profiling:** Pyroscope for Python; pprof for Go.
* **Cloud tracing:** AWS X‑Ray for cross‑service correlation.

**Ops Policies**

* **Error budgets:** e.g., monthly API availability 99.9%; auto‑freeze deploys if budget is exhausted.
* **Runbooks & alerts:** multi‑channel (PagerDuty/Slack); synthetic probes for bridges and RPC health.

## Security & Compliance

**Identity & Secrets**

* **Keycloak**: SSO, **RBAC/ABAC** (tenant, role, workspace).
* **HashiCorp Vault**: dynamic DB creds (short‑lived), signer keys in HSM‑backed KMS; secret rotation every N hours.
* **Network armor:** AWS WAF + Shield; mTLS between services; Least‑Privilege SGs.

**Data Governance**

* **PII boundaries:** segregated VPC & accounts; PII tokens; data minimization.
* **Audit & immutability:** append‑only **Amazon QLDB** for compliance logs (admin actions, model promotions, key events).
* **Compliance posture:** SOC 2 Type II readiness controls (change mgmt, access reviews, DR tests), **GDPR/PDPA** alignment (DPIA, RTBF workflows).

**AppSec & Runtime**

* **Supply chain:** SBOM + image scanning; dep pinning; renovate/bazel for hermetic builds.
* **Runtime guards:** admission controllers (OPA/Gatekeeper), Pod Security, read‑only FS, seccomp & AppArmor.
* **Key paths hardened:** non‑custodial signer isolation, rate‑limited signing endpoints, action allowlists.

### Operational SLOs (suggested)

* **Signal API:** p99 < 120 ms, 99.95% monthly availability.
* **Order submission (router):** p99 < 250 ms (ex‑chain), success rate ≥ 99.5%.
* **Cross‑chain settlement acknowledgment:** p95 < 5 min (bridge‑dependent).
* **Inference (Triton):** on‑box p99 < 10 ms, end‑to‑end p99 < 80 ms.

### Failure Modes & Mitigations (high level)

* **Kafka partition hot‑spotting:** auto‑repartition, sticky keys, producer backoff; surge buffers in Redis.
* **RPC endpoint flaps:** circuit breakers + health weighting → rapid failover; isolate noisy tenants.
* **Bridge congestion/outage:** multi‑bridge routing (L0/Wormhole/XCM) + queue with expirations; user‑visible status.
* **Model drift:** automated canaries + rollback on SLO breach; drift alerts from KS/PSI metrics.
* **Cache stampede:** request coalescing, stale‑while‑revalidate, tiered caches.