FaceTrust AI is the orchestration layer that owns identity data for the FaceTrust product and exposes it as an HTTP API. It does not implement face recognition or hold government identity records itself — it composes two external systems behind thin adapter interfaces:
  • face-engine — face detection, embedding, comparison, and liveness.
  • nin_bvn_simulator — the NIMC (NIN) / NIBSS (BVN) registry stand-in.
Everything else — the relational data model, the pgvector-backed face-embedding index, auth, business rules, and every rule in this doc set — lives in this service.

​
The one rule everything else follows

Linking a NIN or BVN is never a name/number lookup alone. The user must scan their live face, and the API compares that live face against the registry’s own photo, before a link is allowed to complete — and the embedding that ends up in the searchable vector index always comes from that live capture, never from the older registry photo. See Architecture for the full flow.

​
Where to start

  • Quickstart — get the API running locally against both sibling services.
  • Configuration — every environment variable this service reads.
  • Architecture — how the epics map to the code, and the sequencing decisions worth knowing before you touch modules/identity-linking or modules/verification.
  • API Reference — every endpoint, grouped by module.