A model government and municipality governance platform for regulated interactions between the public, commercial, third, and private sectors — built on Sorcha distributed ledger infrastructure.
Status: Technology demonstrator — early development
gov.ex is a civic technology platform that models how government services could work with verifiable digital credentials. Citizens hold licenses, permits, and entitlements in cryptographic wallets. Government departments issue and manage them through customisable workflows. Enforcement officers verify them in real-time at the point of need.
The system is designed around three actors:
| Actor | Role | Identity |
|---|---|---|
| Citizens | Hold credentials in a personal wallet; present them when needed | OAuth anchor (Microsoft, Apple, Google, or third-party) + Sorcha wallet |
| Departments | Define, issue, revoke, and manage credentials for their domain | Existing departmental IAM, federated into gov.ex |
| Enforcement | Verify credentials in real-time at the point of enactment | Authorised department agents with verification access |
Every credential in gov.ex follows a governed lifecycle:
Department defines Citizen receives Citizen presents
credential schema credential in wallet credential on demand
│ │ │
▼ ▼ ▼
┌─────────────┐ Issue ┌──────────────────┐ Present ┌──────────────┐
│ Blueprint │ ──────── │ Citizen Wallet │ ──────── │ Verifier │
│ Service │ │ (Sorcha) │ │ (Officer) │
└─────────────┘ └──────────────────┘ └──────────────┘
│ │
Selective Real-time
Disclosure Pass/Fail
│ │
▼ ▼
Only necessary Minimum data for
attributes shared enforcement context
All issuance and revocation events are recorded on the Sorcha Register — an immutable, cryptographically-secured ledger.
gov.ex is developed as a technology demonstrator across multiple government service domains. Each track proves end-to-end capability from credential definition through to real-time enforcement verification.
Prescriptions, medical credentials, and health entitlements. Demonstrates scenarios such as:
- A GP issuing a prescription credential to a patient's wallet
- A pharmacist verifying the prescription at the point of collection
- Credential expiry and renewal workflows
Refuse collection permits, utility connections, and environmental permits. Demonstrates scenarios such as:
- A council issuing a waste disposal licence
- An enforcement officer verifying a licence at a disposal site
- Cross-council licence recognition (a licence from one authority is verifiable by another)
Benefit entitlements and social service credentials. Demonstrates scenarios such as:
- Issuing a benefit entitlement credential to a citizen's wallet
- A service provider verifying entitlement before providing support
- Credential revocation when circumstances change
gov.ex does not implement its own credential, wallet, or ledger infrastructure. Instead, it builds governance-specific domain layers on top of Sorcha's microservices:
| Sorcha Service | gov.ex Usage |
|---|---|
| Blueprint Service | Government process definitions — application forms, licensing workflows, permit schemas |
| Wallet Service | Citizen credential storage — HD wallets with multi-algorithm crypto (ED25519, NISTP256, RSA-4096) |
| Register Service | Immutable audit trail — every issuance, revocation, and verification event recorded |
| Tenant Service | Department multi-tenancy — each department operates in its own isolated tenancy |
| Validator Service | Consensus on credential issuance and revocation — blockchain validation and docket creation |
| API Gateway | Single entry point — all gov.ex services communicate with Sorcha through YARP-based reverse proxy |
┌────────────────────────────────────────────────────────┐
│ gov.ex Platform │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Citizen │ │ Department │ │ Enforcement │ │
│ │ Portal │ │ Admin │ │ Verifier │ │
│ └──────┬───────┘ └──────┬───────┘ └───────┬───────┘ │
│ │ │ │ │
│ ┌──────┴───────┐ ┌──────┴───────┐ │ │
│ │ OAuth 2.0 / │ │ Dept IAM │ │ │
│ │ OIDC │ │ (SAML/OIDC) │ │ │
│ │ │ │ Federation │ │ │
│ │ - Microsoft │ └──────┬───────┘ │ │
│ │ - Apple │ │ │ │
│ │ - Google │ │ │ │
│ │ - 3rd party │ │ │ │
│ └──────┬───────┘ │ │ │
│ │ │ │ │
│ ┌──────┴─────────────────┴──────────────────┴───────┐ │
│ │ Sorcha Services (API Gateway) │ │
│ └────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
- Citizens authenticate via OAuth providers of their choice (no single-provider lock-in), then create a Sorcha wallet bound to their anchor identity
- Departments integrate their existing IAM systems via standard federation protocols — gov.ex does not replace departmental identity management
- Enforcement officers access verification endpoints through their department's authorisation
| Layer | Technology |
|---|---|
| Runtime | .NET 10 / .NET Aspire |
| Client UI | Blazor WebAssembly (offline-capable, aligned with Sorcha's execution engine) |
| API | Minimal APIs (C#) |
| Identity | OAuth 2.0 / OpenID Connect (citizens), SAML / OIDC federation (departments) |
| Infrastructure | Sorcha distributed ledger services |
| Data | PostgreSQL (tenant/wallet persistence), MongoDB (register/transactions), Redis (caching, SignalR) |
| Real-time | SignalR (notifications, live verification status) |
gov.ex/
├── .claude/ # Claude Code AI agent commands
│ └── commands/
│ ├── speckit.specify.md # Create feature specification
│ ├── speckit.clarify.md # Resolve spec ambiguities
│ ├── speckit.constitution.md # Define/update project principles
│ ├── speckit.plan.md # Generate implementation plan
│ ├── speckit.tasks.md # Generate task list
│ ├── speckit.analyze.md # Cross-artifact consistency check
│ ├── speckit.checklist.md # Domain-specific validation
│ ├── speckit.implement.md # Execute implementation
│ └── speckit.taskstoissues.md # Convert tasks to GitHub issues
│
├── .specify/ # Specify framework
│ ├── memory/
│ │ └── constitution.md # Project principles & governance (v1.0.0)
│ ├── scripts/powershell/ # Automation scripts
│ └── templates/ # Artifact templates (spec, plan, tasks, etc.)
│
├── specs/ # Feature specifications (created per feature)
│ └── NNN-feature-name/
│ ├── spec.md # Business requirements
│ ├── plan.md # Technical design
│ ├── tasks.md # Implementation task list
│ └── ... # Research, data models, contracts
│
├── CLAUDE.md # AI agent guidance for this repo
└── README.md # This file
Source code directories (src/, backend/, frontend/, etc.) will be created as features are implemented.
gov.ex uses the Specify framework — a structured, specification-driven approach to feature development powered by AI agents (Claude Code).
/speckit.constitution Define project principles (done once, amended as needed)
│
▼
/speckit.specify Write business-focused feature spec
│
▼
/speckit.clarify Resolve ambiguities (max 3 [NEEDS CLARIFICATION] markers)
│
▼
/speckit.plan Generate technical plan + research + data model
│
▼
/speckit.tasks Generate phased task list organised by user story
│
▼
/speckit.analyze Validate consistency across spec ↔ plan ↔ tasks
│
▼
/speckit.implement Execute tasks with checkpoint validation
│
▼
/speckit.taskstoissues Convert remaining tasks to GitHub issues
| Entity | Format | Example |
|---|---|---|
| Feature branch & directory | NNN-short-name |
001-citizen-wallet |
| Task IDs | TXXXX |
T0012 |
| Functional requirements | FR-XXX |
FR-001 |
| Success criteria | SC-XXX |
SC-003 |
| User stories | User Story N - [Title] (Priority: P1) |
User Story 1 - Prescription Issuance (Priority: P1) |
When development reveals a missing capability in Sorcha:
- Document the requirement or issue
- Raise it against the Sorcha repository
- If a workaround is needed in gov.ex, mark it with
// SORCHA-GAP: <description> - Track for removal once the upstream capability ships
- .NET 10 SDK
- Git
- PowerShell 5.0+
- Claude Code (for Specify workflow commands)
- Sorcha services running locally (Docker Compose recommended)
# Clone the repository
git clone https://github.com/stuartf303/gov.ex.git
cd gov.ex
# Start Sorcha services (see Sorcha repo for Docker Compose setup)
# Sorcha API Gateway will be available at http://localhost/
# API documentation at http://localhost/scalar/
# Begin feature development using Specify workflow
# (Run these commands in Claude Code)
/speckit.constitution # Review/update project principles
/speckit.specify # Start specifying a new featureThe project is governed by a constitution (v1.0.0) that gates all design decisions:
- Sorcha-First Infrastructure — All credential/wallet/ledger operations delegate to Sorcha; never duplicate its functionality
- Federated Identity with Citizen Sovereignty — Citizens choose their identity provider; wallets enable selective disclosure
- Credential Lifecycle Integrity — Every credential follows: issuance → holding → presentation → verification → revocation
- Real-Time Verification at Point of Enactment — Enforcement officers verify credentials instantly with minimum data exposure
- Departmental Autonomy within System Coherence — Customisable department interfaces; same API contracts system-wide
- Track-Based Demonstrator Development — Health, Licensing, and Social Support tracks prove end-to-end capability
This project is currently in early development as a technology demonstrator. The repository is private.
When contributing:
- Follow the Specify workflow — start with a spec, not with code
- Validate all designs against the constitution
- Use RFC-style requirement language (MUST, SHOULD, MAY)
- Each user story must be independently testable and deployable
- Mark any Sorcha capability gaps with
// SORCHA-GAP:comments
Private — not yet licensed for distribution.