# authed-dev/authed-identity architecture

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

- Interactive diagram: https://gitdiagram.com/authed-dev/authed-identity
- Repository: https://github.com/authed-dev/authed-identity

## Overview

##### Project Type and Purpose
- The project is an identity and authentication system for AI agents. It provides components that enable secure agent-to-agent communication, dynamic identity management, and token-based authentication.
- It’s a developer-first, open-source protocol with a CLI, SDK for integrations (including FastAPI examples), a registry server for managing identities and tokens, and integrations with protocols like MCP.

##### Main Components
a. CLI Interface:
- Components under the “authed/cli” directory (commands, utilities) handling setup, agent initialization, key management, permission and log management.
- This as a “CLI / Command Interface” component.
b. Core SDK and Library:
- The “authed/sdk” directory shows modules for authentication (agent_auth, tokens, DPoP), secure channel management (using WebSockets), decorators (incoming/outgoing for HTTP clients), and testing utilities.
- This should be depicted as the “Core SDK & Authentication Library” that provides reusable functions and integrations for agent identity.
c. Registry Subsystem:
- The “registry” directory contains the API, middleware for auth, CORS, rate limiting, and service layers (agent_service, permission_service, provider_service, token_service). It also has a database layer (“registry/db”) for persistence (models, migrations, sessions, Redis).
d. Integrations:
- There is an “integrations/mcp” directory that implements an integration layer for the Model Context Protocol (MCP), along with examples of client and server implementations.
- This component as “MCP Integration” representing how Authed plugs into external protocols.
e. Demo Applications:
- The “demo” directory includes both a “client” (with a bridge component) and a “server” example. They serve as sample implementations to demonstrate how clients interact with and use the Authed SDK.
- A “Demo / Sample Applications” component showing client–server interactions.
f. Deployment and Infrastructure:
- The “k8s” directory holds configurations for deploying components to a Kubernetes environment, including ingress controllers, deployments, HPA, config maps, and secrets.
- This as the “Deployment / Kubernetes” environment that hosts the runtime services.

##### Relationships and Interactions
- That the Registry component interacts with the SDK and serves as a central backend for handling identity registration, token issuance, and auditing (logging).
- The SDK’s secure channel module should point toward external AI agents communicating via WebSockets (depicted as “Agent-to-Agent Communication”), emphasizing authentication flows.
- For integrations, display bi-directional interactions between the Authed system and the MCP-enabled systems.

##### Architectural Patterns and Design Principles
- The project follows a modular structure, separating the CLI, SDK, and registry microservice. This separation enables discrete and isolated development of command-line tools, authentication logic, and API services.
- Dependency inversion appears in how the SDK abstracts protocol security (websocket channels, decorators for HTTPx, fastAPI) while allowing integration with various frameworks.
- Use of middleware for tasks like rate limiting, CORS, and authentication within the registry indicates concern for security and scalability.
- The usage of Kubernetes manifests signifies that the system is designed for containerized, cloud-native deployments.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend Components"
        CLI["Authed CLI"]:::cli
        Demo["Demo / Sample Applications"]:::demo
    end

    subgraph "Core Services"
        SDK["Authentication SDK"]:::sdk
        Registry["Registry API"]:::registry
    end

    subgraph "Integrations"
        MCP["MCP Integration"]:::mcp
    end

    subgraph "Deployment and Infrastructure"
        K8s["Kubernetes Deployment"]:::k8s
    end

    External["Agent-to-Agent Communication"]:::external

    %% Relationships
    CLI -->|"calls"| SDK
    Demo -->|"invokes"| SDK
    SDK -->|"authenticates"| Registry
    SDK -->|"secureChannel"| External
    SDK <-->|"integrates"| MCP
    K8s -->|"deploys"| Registry

    %% Click Events
    click CLI "https://github.com/authed-dev/authed-identity/tree/main/authed/cli"
    click SDK "https://github.com/authed-dev/authed-identity/tree/main/authed/sdk"
    click Registry "https://github.com/authed-dev/authed-identity/tree/main/registry"
    click MCP "https://github.com/authed-dev/authed-identity/tree/main/integrations/mcp"
    click Demo "https://github.com/authed-dev/authed-identity/tree/main/demo"
    click K8s "https://github.com/authed-dev/authed-identity/tree/main/k8s"

    %% Styles
    classDef cli fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef sdk fill:#C0F9BD,stroke:#333,stroke-width:2px;
    classDef registry fill:#FFEDB8,stroke:#333,stroke-width:2px;
    classDef mcp fill:#D5BFF7,stroke:#333,stroke-width:2px;
    classDef demo fill:#F8D7DA,stroke:#333,stroke-width:2px;
    classDef k8s fill:#E2E2E2,stroke:#333,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#333,stroke-width:2px;
```
