How agntcy/identity-service works
Project Type & Purpose
• This is a full-stack, API-First Identity Management platform.
• It provides gRPC & REST services for digital identity (apps, badges, devices, TBAC policies), a React-based administrative UI, multi-language SDKs, sample agents, docs, and Helm/Compose deployments.
File Structure Highlights
• Top‐level dirs:
• backend/ – Go monolith broken into:
– api/spec & api/server → Protobuf definitions → gRPC server + HTTP gateway
– api/client → Generated Go client
– cmd/bff → BFF (Backend-for-Frontend) serving REST & gRPC endpoints
– internal/core → Domain logic per bounded context (app, auth, badge, device, policy, settings, identity) + persistence (Postgres repos)
– internal/pkg → Shared utilities (interceptors, JWT/OIDC, vault, caching, error handling)
• frontend/ – React + TypeScript SPA using generated OpenAPI clients
• sdk/python/ – Python gRPC & HTTP SDK
• samples/ – Example A2A, MCP, OASf agent implementations
• charts/, deployments/ – Helm charts & Docker-Compose definitions
• docs/ – Docusaurus site, API protodocs
README Insights
• Main Components: Backend, Frontend, SDKs, Docs, Samples
• Backend exposes:
• REST endpoints at http://localhost:4000
• gRPC at http://localhost:4001
• Frontend served at http://localhost:5500
• Integrations: OIDC provider (Hydra/Keycloak/Auth0), Vault for secrets
Essential Detail
• Service with its name and purpose
• Where interceptors and JWT verification occur
• Codegen steps for client libraries and OpenAPI specs