OpenResidency — Concepts & Architecture
The mental model for OpenResidency — the roles, actors, trust flow, and architecture behind subnational Residency IDs, Verifiable Credentials, and cross-sector single sign-on.
What it does, in plain terms
A resident walks into a government office. A member of staff checks them against the national register — NIN in Nigeria, Aadhaar in India, whichever register the state already uses — and confirms two separate things: that the identity record is genuine, and that this is the person it belongs to.
The resident walks out with a residency credential. It lives on their phone, and it proves they live in this state.
Three things about that credential matter:
- It works without internet. Anyone can check it is genuine and unaltered without calling a server — which matters in a market, at a rural clinic, or when the network is down.
- It replaces the paperwork, not just the queue. They use it to sign in to health, tax, permits, subsidy and education services. One credential, every counter.
- Each service learns only what the resident agreed to share. The clinic can be told the person is a resident of this ward without being told their national ID number — and the tax office and the clinic cannot compare notes to work out they are the same person.
The national ID number itself is never stored. Only a one-way reference to it is kept, so a database breach does not spill a register of national identity numbers.
For a state adopting it, a new jurisdiction is one configuration file — not a fork of the software.
This site is the concept and architecture map: the shared mental model behind all of that.
It is a companion to the code, not a replacement — every concept links to the file or class where
it lives in open-residency.
One layer, not the whole platform
OpenResidency is the identity/residency/SSO layer (the "SIEI" layer of the wider State DPI framework). Data exchange, payments, e-invoicing, and analytics are separate systems on the roadmap — they are not in this codebase. Keep that boundary sharp.
Concepts
Verifiable Credentials
Issuer, Holder, Verifier — the three roles the whole system is built on.
Roles & role mapping
How Issuer/Holder/Verifier map to the Provider, the code, relying parties, and operators.
The actor catalog
Every principal, by trust tier: anonymous, human, machine, external system.
How it works
The trust flow
Deployer → operator enrols → credential issued → citizen signs in → consent & audit.
Architecture
The core / delivery / ports split — hexagonal, and why the core is the real asset.
Credentials & trust
Trust artifacts, offline verification, and how VcVerifier and VpVerifier differ.
Building on it
What not to break
The security invariants that are the whole point of the system.
Contributing
The workflow: issue → core-behind-boundary → assertion → green → signed PR.
Glossary
DID, VC, VP, VC-JWT, OID4VCI/VP, subjectRef, pairwise sub, RAL, and more.
The one-paragraph version. A citizen is verified against a national ID source (NIN, Aadhaar, Huduma — over REST, SOAP/X-Road, or an imported register); the raw national number is never stored, only a tokenized reference. They are issued a signed residency credential that verifies offline, and use it to sign in once across sectors — where each service receives a different opaque identifier and only the claims the citizen consented to, never the national ID. A new jurisdiction is one YAML file, not a fork.