# agntcy/identity-service architecture

> Architecture diagram of the GitHub repository agntcy/identity-service, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agntcy/identity-service
- Repository: https://github.com/agntcy/identity-service

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend & Browser
    subgraph "Browser & Frontend"
        Browser["Browser (React SPA)"]:::services
        Frontend["SPA (frontend/)"]:::services
        OpenAPIClient["Generated OpenAPI Client"]:::generated
    end

    %% API Gateway
    subgraph "API Gateway (BFF)"
        BFF["cmd/bff API Gateway"]:::services
        BFF_Utils["BFF Supporting Code (internal/bff)"]:::services
    end

    %% Backend Services
    subgraph "Backend Services"
        subgraph "API & Transport"
            ProtoSpecs["Protobuf Definitions"]:::services
            GRPCServer["gRPC Server + HTTP Gateway"]:::services
        end
        subgraph "Domain Services"
            AppService["AppService"]:::services
            AuthService["AuthService"]:::services
            BadgeService["BadgeService"]:::services
            DeviceService["DeviceService"]:::services
            PolicyService["PolicyService"]:::services
            SettingsService["SettingsService"]:::services
            IdentityService["IdentityService"]:::services
            IAM["IAM Support"]:::services
            IDP["IDP Integrations"]:::services
        end
        subgraph "Shared Infrastructure"
            Interceptors["Interceptors"]:::services
            JWT["JWT Utilities"]:::services
            OIDC["OIDC Utilities"]:::services
            VaultPkg["Vault Client"]:::services
            Cache["In-Memory Cache"]:::services
            HTTPUtil["HTTP Utilities"]:::services
            ErrUtil["Error Utilities"]:::services
            Pagination["Pagination"]:::services
            WebPush["WebPush Utils"]:::services
        end
    end

    %% Infrastructure & External Systems
    subgraph "Infrastructure & External"
        Postgres["PostgreSQL"]:::database
        Vault["Vault"]:::database
        OIDCProvider["OIDC Provider"]:::external
        PushSMTP["Push/SMTP Server"]:::external
    end

    %% SDKs & Samples
    subgraph "Clients & SDKs"
        GoClient["Go Client SDK"]:::generated
        PySDK["Python SDK"]:::generated
        SamplesA2A["Sample Agents (A2A)"]:::generated
        SamplesMCP["Sample Agents (MCP)"]:::generated
        SampleCharts["Sample Helm Charts"]:::generated
    end

    %% Documentation
    subgraph "Documentation"
        DocsSite["Docs Site"]:::generated
        ProtoDocs["Generated Protodocs"]:::generated
        StaticOpenAPI["Static OpenAPI Output"]:::generated
    end

    %% CI/CD & Deployment
    subgraph "CI/CD & Deployment"
        CI["GitHub Actions"]:::external
        HelmCharts["Helm Charts"]:::external
        Compose["Docker-Compose"]:::external
        DockerScripts["Dockerfiles & Scripts"]:::external
    end

    %% Connections
    Browser -->|HTTPS REST| BFF
    Frontend -->|REST| BFF
    BFF -->|gRPC| GRPCServer
    BFF -->|JWT/OIDC Validation| OIDCProvider
    ProtoSpecs -->|defines| GRPCServer
    GRPCServer -->|calls| AppService
    GRPCServer --> AuthService
    GRPCServer --> BadgeService
    GRPCServer --> DeviceService
    GRPCServer --> PolicyService
    GRPCServer --> SettingsService
    GRPCServer --> IdentityService
    GRPCServer --> IAM
    GRPCServer --> IDP
    AppService -->|SQL| Postgres
    AuthService --> Postgres
    BadgeService --> Postgres
    DeviceService --> Postgres
    PolicyService --> Postgres
    SettingsService --> Postgres
    IdentityService --> Postgres
    AppService -->|Vault API| Vault
    AuthService --> Vault
    BFF_Utils --> Interceptors
    Interceptors -->|uses| JWT
    Interceptors -->|uses| OIDC
    SharedInfraNodes---GRPCServer
    SamplesA2A -->|gRPC via GoClient/PySDK| GRPCServer
    SamplesMCP -->|gRPC via GoClient/PySDK| GRPCServer
    CI -->|codegen from| ProtoSpecs
    CI -->|build images| DockerScripts
    CI -->|deploy charts| HelmCharts
    CI -->|deploy compose| Compose
    StaticOpenAPI -->|used by| Frontend
    StaticOpenAPI -->|docs| DocsSite
    ProtoDocs -->|docs| DocsSite

    %% Click Events
    click Frontend "https://github.com/agntcy/identity-service/tree/main/frontend/"
    click OpenAPIClient "https://github.com/agntcy/identity-service/tree/main/frontend/generated/openapi"
    click BFF "https://github.com/agntcy/identity-service/tree/main/backend/cmd/bff"
    click BFF_Utils "https://github.com/agntcy/identity-service/tree/main/backend/internal/bff"
    click ProtoSpecs "https://github.com/agntcy/identity-service/tree/main/backend/api/spec/proto/agntcy/identity/service/v1alpha1/"
    click GRPCServer "https://github.com/agntcy/identity-service/tree/main/backend/api/server/agntcy/identity/service/v1alpha1/"
    click GoClient "https://github.com/agntcy/identity-service/tree/main/backend/api/client"
    click AppService "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/app"
    click AuthService "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/auth"
    click BadgeService "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/badge"
    click DeviceService "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/device"
    click PolicyService "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/policy"
    click SettingsService "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/settings"
    click IdentityService "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/identity"
    click IAM "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/iam"
    click IDP "https://github.com/agntcy/identity-service/tree/main/backend/internal/core/idp"
    click Interceptors "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/interceptors"
    click JWT "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/jwtutil"
    click OIDC "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/oidc"
    click VaultPkg "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/vault"
    click Cache "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/cache"
    click HTTPUtil "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/httputil"
    click ErrUtil "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/errutil"
    click Pagination "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/pagination"
    click WebPush "https://github.com/agntcy/identity-service/tree/main/backend/internal/pkg/webpush"
    click PySDK "https://github.com/agntcy/identity-service/tree/main/sdk/python/agntcy/identity/service"
    click SamplesA2A "https://github.com/agntcy/identity-service/tree/main/samples/agent"
    click SamplesMCP "https://github.com/agntcy/identity-service/tree/main/samples/mcp"
    click SampleCharts "https://github.com/agntcy/identity-service/tree/main/samples/charts/identity-sample-*"
    click HelmCharts "https://github.com/agntcy/identity-service/tree/main/charts/identity-service-backend"
    click Compose "https://github.com/agntcy/identity-service/tree/main/deployments/docker-compose"
    click DockerScripts "https://github.com/agntcy/identity-service/tree/main/deployments/scripts"
    click DocsSite "https://github.com/agntcy/identity-service/tree/main/docs/"
    click ProtoDocs "https://github.com/agntcy/identity-service/tree/main/docs/protodocs/agntcy/identity/service"
    click StaticOpenAPI "https://github.com/agntcy/identity-service/tree/main/backend/api/spec/static/api/openapi"

    %% Styles
    classDef services fill:#D0E8FF,stroke:#0366d6;
    classDef database fill:#DFFFE0,stroke:#28a745;
    classDef external fill:#FFE4B5,stroke:#FF8C00;
    classDef generated fill:#EDEDED,stroke:#6a737d;
```
