# akramiot/agentic-iam architecture

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

- Interactive diagram: https://gitdiagram.com/akramiot/agentic-iam
- Repository: https://github.com/akramiot/agentic-iam

## Overview

##### Project Type and Purpose
- This is a modular Python framework (library + service) for managing agent identities, authentication, authorization, sessions, audit/compliance, federated identity, credential management, and ML-based trust scoring.
- It exposes an HTTP API (FastAPI) and includes a dashboard component. It can be deployed via Docker/Kubernetes and integrated into larger systems.

##### File Structure
- Top-level containers:
- api/ (FastAPI routers: audit, authorization, intelligence, sessions)
- core/ (business logic: agentic_iam)
- dashboard/ (UI components for management)
- config/ (settings.py environment mapping)
- utils/ (shared logger)
- scripts/ (migration, metrics, security tasks)
- monitoring/ (Prometheus configuration)
- k8s/ & Dockerfile/docker-compose.yml (deployment manifests)
- main.py & api/main.py (service entrypoints)
- tests/ (unit & integration)
- Configuration: pyproject.toml, requirements.txt, pytest.ini, conftest.py.

##### README for Additional Insights
- Core components listed in “Architecture” section align with folder names: AgentIdentity, Authentication, Authorization, SessionManager, FederatedIdentity, CredentialManager, AgentRegistry, TransportBinding, AuditCompliance, AgentIntelligence.
- Deployment recommendations include optional backends (PostgreSQL, Redis, HSM), monitoring (Prometheus/Grafana), and federation (OIDC, SAML, DIDComm).

- API Gateway / HTTP Server (FastAPI)
- Core Service Modules
– Authentication Subsystem
– Authorization Engine
– Session Manager
– Credential Manager
– Agent Registry
– Federated Identity Adapter
– Audit & Compliance Manager
– Agent Intelligence Engine
- Dashboard UI Service
- Data Stores
– Primary DB (SQLite / PostgreSQL)
– Session Store (In-memory / Redis)
– Audit Storage (SQLite / External)
– Credential Vault (in-memory / file / HSM)
- External Identity Providers
– OIDC Provider
– SAML IdP
– Trust Brokers (DIDComm)
- Messaging / Transport
– HTTP/HTTPS
– gRPC / WebSocket / STDIO
- Monitoring Stack
– Prometheus
– (Grafana optional)

– Agents/Clients → HTTP/gRPC → API Gateway
– API Gateway → Authentication → Authorization → Session Manager
– Session Manager ↔ Session Store
– Authorized requests → Core Modules (Registry, Credential, Audit, Intelligence)
– Core Modules ↔ Data Stores
– Federated Identity ↔ External IdPs
– Audit & Compliance → Audit Storage
– Agent Intelligence ← Audit Events
– Dashboard UI ⟷ API Gateway

c. Architectural Patterns
- Modular, layered service (clear separation: transport, business logic, persistence)
- Pluggable backends via abstraction interfaces (in-memory, file, SQL, HSM)
- Async/non-blocking I/O in API and intelligence components
- Zero-trust principle: all requests authenticated and authorized
- Micro-pattern within a monolithic service (could be refactored into microservices if needed)

d. Relevant Technologies/Frameworks
- FastAPI for API
- Python asyncio for non-blocking operations
- SQLAlchemy or direct SQLite/PostgreSQL drivers
- JWT, Ed25519/RSA cryptography libraries
- Prometheus exporter
- Docker & Kubernetes manifests
- pytest for testing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients
    Clients["Agents/Clients"]:::external

    %% API Layer
    subgraph "API Layer"
        direction TB
        APIGateway["API Gateway / HTTP Server"]:::api
        TransportBinding["API Data Models (Transport Binding)"]:::api
        AuthenticationAPI["Authentication Router"]:::api
        AuthorizationAPI["Authorization Router"]:::api
        SessionAPI["Session Router"]:::api
        AuditAPI["Audit Router"]:::api
        IntelligenceAPI["Intelligence Router"]:::api
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        AuthCore["Authentication Subsystem"]:::core
        AuthZCore["Authorization Engine"]:::core
        SessionCore["Session Manager"]:::core
        CredentialManager["Credential Manager"]:::core
        AgentRegistry["Agent Registry"]:::core
        FederatedIdentity["Federated Identity Adapter"]:::core
        AuditCore["Audit & Compliance Manager"]:::core
        IntelligenceCore["Agent Intelligence Engine"]:::core
    end

    %% Config & Utils
    subgraph "Config & Utilities"
        direction TB
        Config["Configuration Settings"]:::util
        Logger["Logger Utility"]:::util
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        PrimaryDB["Primary DB (SQLite/PostgreSQL)"]:::datastore
        SessionStore["Session Store (Redis)"]:::datastore
        AuditStorage["Audit Storage"]:::datastore
        CredentialVault["Credential Vault (HSM/File)"]:::datastore
    end

    %% External Systems
    subgraph "External Identity Providers"
        direction TB
        OIDC["OIDC Provider"]:::external
        SAML["SAML IdP"]:::external
        DIDComm["Trust Broker (DIDComm)"]:::external
    end

    %% Dashboard
    Dashboard["Dashboard UI Service"]:::external

    %% Monitoring
    subgraph "Monitoring"
        direction TB
        Prometheus["Prometheus"]:::monitoring
        Grafana["Grafana (optional)"]:::monitoring
    end

    %% Deployment
    subgraph "Deployment"
        direction TB
        Container["Docker Container"]:::deployment
        K8s["Kubernetes Cluster"]:::deployment
        ConfigMap["ConfigMap & Secrets"]:::deployment
    end

    %% Scripts
    subgraph "Scripts"
        direction TB
        Migrate["Database Migrations Script"]:::scripts
        PerfMetrics["Performance Metrics Script"]:::scripts
        SecHardening["Security Hardening Script"]:::scripts
    end

    %% Tests
    subgraph "Tests"
        direction TB
        IntegrationTests["Integration Tests"]:::tests
        UnitAuthTests["Unit Tests – API Authentication"]:::tests
        UnitCoreTests["Unit Tests – Core Agentic IAM"]:::tests
    end

    %% Flows
    Clients -->|HTTP/gRPC| APIGateway
    APIGateway --> TransportBinding
    TransportBinding --> AuthenticationAPI
    TransportBinding --> AuthorizationAPI
    TransportBinding --> SessionAPI
    TransportBinding --> AuditAPI
    TransportBinding --> IntelligenceAPI

    AuthenticationAPI -->|calls| AuthCore
    AuthorizationAPI -->|calls| AuthZCore
    SessionAPI -->|calls| SessionCore
    AuditAPI -->|calls| AuditCore
    IntelligenceAPI -->|calls| IntelligenceCore

    AuthCore --> PrimaryDB
    AuthZCore --> PrimaryDB
    SessionCore --> SessionStore
    AuditCore --> AuditStorage
    CredentialManager --> CredentialVault
    AgentRegistry --> PrimaryDB
    FederatedIdentity --> OIDC
    FederatedIdentity --> SAML
    FederatedIdentity --> DIDComm
    IntelligenceCore --> AuditStorage

    Dashboard -->|HTTP| APIGateway

    Config --> APIGateway
    Config --> AuthCore
    Logger --> AuthCore
    Logger --> AuthZCore
    Logger --> SessionCore
    Logger --> AuditCore
    Logger --> IntelligenceCore

    Container --> APIGateway
    Container --> Dashboard
    Container --> Prometheus
    K8s --> Container
    ConfigMap --> Container

    Prometheus -->|scrapes| APIGateway
    Prometheus -->|scrapes| AuthCore

    Migrate --> PrimaryDB
    PerfMetrics --> Prometheus
    SecHardening --> Container

    IntegrationTests --> APIGateway
    UnitAuthTests --> AuthenticationAPI
    UnitCoreTests --> AuthCore

    %% Click Events
    click APIGateway "https://github.com/akramiot/agentic-iam/blob/main/main.py"
    click APIGateway "https://github.com/akramiot/agentic-iam/blob/main/api/main.py"
    click AuthCore "https://github.com/akramiot/agentic-iam/blob/main/core/agentic_iam.py"
    click AuthorizationAPI "https://github.com/akramiot/agentic-iam/blob/main/api/routers/authorization.py"
    click SessionAPI "https://github.com/akramiot/agentic-iam/blob/main/api/routers/sessions.py"
    click AuditAPI "https://github.com/akramiot/agentic-iam/blob/main/api/routers/audit.py"
    click IntelligenceAPI "https://github.com/akramiot/agentic-iam/blob/main/api/routers/intelligence.py"
    click TransportBinding "https://github.com/akramiot/agentic-iam/blob/main/api/models.py"
    click Config "https://github.com/akramiot/agentic-iam/blob/main/config/settings.py"
    click Dashboard "https://github.com/akramiot/agentic-iam/blob/main/dashboard/components/agent_management.py"
    click Logger "https://github.com/akramiot/agentic-iam/blob/main/utils/logger.py"
    click Migrate "https://github.com/akramiot/agentic-iam/blob/main/scripts/migrate.py"
    click PerfMetrics "https://github.com/akramiot/agentic-iam/blob/main/scripts/performance_metrics.py"
    click SecHardening "https://github.com/akramiot/agentic-iam/blob/main/scripts/security_hardening.py"
    click Prometheus "https://github.com/akramiot/agentic-iam/blob/main/monitoring/prometheus/prometheus.yml"
    click Container "https://github.com/akramiot/agentic-iam/tree/main/Dockerfile"
    click Container "https://github.com/akramiot/agentic-iam/blob/main/docker-compose.yml"
    click K8s "https://github.com/akramiot/agentic-iam/blob/main/k8s/configmap.yaml"
    click K8s "https://github.com/akramiot/agentic-iam/blob/main/k8s/deployment.yaml"
    click K8s "https://github.com/akramiot/agentic-iam/blob/main/k8s/namespace.yaml"
    click IntegrationTests "https://github.com/akramiot/agentic-iam/blob/main/tests/test_integration/test_api_integration.py"
    click UnitAuthTests "https://github.com/akramiot/agentic-iam/blob/main/tests/test_unit/test_api/test_authentication.py"
    click UnitCoreTests "https://github.com/akramiot/agentic-iam/blob/main/tests/test_unit/test_core/test_agentic_iam.py"

    %% Styles
    classDef api fill:#add8e6,stroke:#333,stroke-width:1px
    classDef core fill:#90ee90,stroke:#333,stroke-width:1px
    classDef datastore fill:#ffcc80,stroke:#333,stroke-width:1px
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef monitoring fill:#fff176,stroke:#333,stroke-width:1px
    classDef util fill:#e1bee7,stroke:#333,stroke-width:1px
    classDef scripts fill:#f8bbd0,stroke:#333,stroke-width:1px
    classDef deployment fill:#b3e5fc,stroke:#333,stroke-width:1px
    classDef tests fill:#cfd8dc,stroke:#333,stroke-width:1px
```
