We never touched a live government system
The competition brief prohibits accessing or interfering with live government systems, and it is also simply the right call. So the only integration surface in this project is a mock gateway that we specified and built ourselves: a separate process with its own OpenAPI description.
The endpoints it exposes
| Endpoint | Returns |
|---|---|
GET /v1/member/{uan}/profile | Demographics and KYC verification states |
GET /v1/member/{uan}/service-history | Member IDs, joining and exit dates, establishment, status |
GET /v1/member/{uan}/kyc | Aadhaar, PAN and bank verification states with match flags |
POST /v1/joint-declaration | A tracking reference for a correction request |
POST /v1/claim | Simulated filing. Dry-run only. |
POST /v1/grievance | A grievance-shaped payload. Sent nowhere. |
Why a mock is better than a hand-wave
Anyone can write "we would integrate with the API." Specifying the interface forces you to decide what the request and response actually look like, what the error codes are, and what happens when the upstream is slow. Our gateway can inject 500s, eight-second latencies and partial responses on demand, because that is what a real government integration does. A product that has never seen its dependency fail is a product that will fail in the field.
The adapter boundary
There is exactly one interface between Kosh and any government system. MockAdapter implements it and ships. EpfoAdapter exists as a deliberately unimplemented stub with a comment explaining that implementing it requires an MoU and authorised endpoints. Pointing it at the live portal would violate the brief.
In production the same boundary is where DigiLocker or API Setu, Account Aggregator for bank records, and Aadhaar e-Sign through a licensed provider would attach. Nothing else in the codebase changes.