> For the complete documentation index, see [llms.txt](https://docs.openg2p.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openg2p.org/platform/platform-services/id-generator.md). # ID Generator A service that generates unique, random numeric IDs for multiple consuming applications with pre-generated pools, Verhoeff checksum, and multi-ID-type support. ## Overview The ID Generator service produces unique, random numeric IDs for applications such as social registries, farmer registries, health systems, and more. Each consuming application operates within its own **ID type**, with an independent pool of pre-generated IDs. The service is built with **FastAPI**, uses **PostgreSQL** for storage, and is designed for **horizontal scaling on Kubernetes**. ### Key capabilities * **Multi-ID-type support** — Each application (farmer ID, household ID, national ID, etc.) gets an independent ID pool with configurable ID length. * **Pre-generated pool** — IDs are generated in advance and stored in PostgreSQL, ensuring fast issuance with no generation delay at request time. * **10 filter rules** — Comprehensive ID quality filters (inspired by [MOSIP UIN generation filters](https://docs.mosip.io/1.2.0/id-lifecycle-management/supporting-components/commons/id-generator#uin-generation-filters)) plus Verhoeff checksum ensure ID quality. * **Kubernetes-native** — Horizontally scalable with zero-contention ID issuance and coordinated pool replenishment across pods. * **Structural validation** — Downstream systems can validate any ID without a database lookup. ### How it works ``` 1. On startup → create tables, fill ID pools to minimum threshold 2. On request → atomically issue one pre-generated ID (AVAILABLE → TAKEN) 3. In background → monitor pool levels, replenish when low ``` ### ID lifecycle IDs follow a simple two-state model: ``` AVAILABLE → TAKEN ``` * **AVAILABLE** — In pool, ready to be issued. * **TAKEN** — Issued to a caller; permanently consumed. Never re-issued. ## Detailed documentation | Page | Description | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | [Functional Specifications](/platform/platform-services/id-generator/functional-specifications.md) | ID types, generation rules, 10 filter rules, pool management, exhaustion handling, configuration | | [API Reference](/platform/platform-services/id-generator/api-reference.md) | REST API endpoints, request/response formats, error codes, OpenAPI spec | | [Technical Architecture](/platform/platform-services/id-generator/technical-architecture.md) | Async stack, database design, concurrency patterns, Kubernetes deployment | | [Deployment](/platform/platform-services/id-generator/deployment.md) | Helm chart installation, Docker setup, local development, environment variables | | [Testing](/platform/platform-services/id-generator/testing.md) | Test categories, execution commands, HTML reporting | ## Versions Every version, with its changes: [ID Generator changelog](https://openg2p.github.io/versions/id-generator/CHANGELOG.html). The `openg2p-id-generator` chart and the `openg2p/openg2p-id-generator` image carry the same version. How versions are derived: [Helm & Docker Versioning Strategy and CI](/operations/deployment/helm-docker-versioning-and-ci.md). ### Earlier versions The changelog starts at 1.1.0 (2026-07-14). Earlier release: | Helm Chart Version | Docker Image | Date | Comments | | ----------------------------------------------------------- | ------------------------------------ | ---------- | -------------- | | [1.0.0](https://github.com/OpenG2P/id-generator/tree/1.0.0) | `openg2p/openg2p-id-generator:1.0.0` | 2026-04-17 | Stable version | ## Source code * GitHub: ## Technology stack | Component | Choice | License | | ------------- | ---------------------- | ------------------------------- | | Language | Python 3.11+ | PSF License (permissive) | | Web Framework | FastAPI | MIT | | ASGI Server | Uvicorn | BSD-3-Clause | | DB Driver | asyncpg | Apache 2.0 | | ORM | SQLAlchemy 2.x (async) | MIT | | Config | Pydantic Settings | MIT | | Database | PostgreSQL | PostgreSQL License (permissive) | | Deployment | Kubernetes + Helm | Apache 2.0 | All components use **permissive open-source licenses**. No copyleft (GPL) dependencies. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openg2p.org/platform/platform-services/id-generator.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.