> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.adid.dev/llms.txt.
> For full documentation content, see https://docs.adid.dev/llms-full.txt.

# Platform Architecture

## System Architecture

IDA is a multi-layered decentralized identity platform. The architecture separates concerns into client applications, platform services, the ADI blockchain layer, and decentralized storage.

```mermaid
graph TB
    subgraph "Client Layer"
        HW[Holder Wallet<br />Mobile/Web]
        IP[Issuer Portal<br />React Web App]
        VP[Verifier Portal<br />React Web App]
        SDK[AI Agent SDK<br />MCP/A2A/API]
    end

    subgraph "API Gateway"
        GW[Kong / Envoy<br />Rate Limiting, Auth, LB]
    end

    subgraph "Service Layer"
        DID[DID Service<br />Create/Resolve/Update/Deactivate]
        VC[VC Service<br />Issue/Verify/Revoke/Present]
        AGT[Agent Service<br />DIDComm, Messaging, Mediation]
        AID[AI Agent Identity Service<br />Agent DID, Delegation, Trust]
    end

    subgraph "Data Layer"
        PG[(PostgreSQL<br />Off-chain Index)]
        RD[(Redis<br />Cache)]
        MQ[NATS / RabbitMQ<br />Message Queue]
    end

    subgraph "ADI Blockchain"
        DR[DID Registry<br />Smart Contract]
        SR[Schema Registry<br />Smart Contract]
        RR[Revocation Registry<br />Smart Contract]
        ATR[Agent Trust Registry<br />Smart Contract]
    end

    subgraph "Decentralized Storage"
        IPFS[IPFS / ADI Storage<br />DID Docs, Schemas, Agent Cards]
    end

    HW --> GW
    IP --> GW
    VP --> GW
    SDK --> GW

    GW --> DID
    GW --> VC
    GW --> AGT
    GW --> AID

    DID --> PG
    DID --> RD
    DID --> DR

    VC --> PG
    VC --> SR
    VC --> RR

    AGT --> MQ
    AGT --> PG

    AID --> ATR
    AID --> PG

    DR --> IPFS
    SR --> IPFS
    ATR --> IPFS
```

## Component Overview

### 1. Client Layer

| Component       | Technology             | Purpose                                              |
| --------------- | ---------------------- | ---------------------------------------------------- |
| Holder Wallet   | React Native / Flutter | Key management, credential storage, presentations    |
| Issuer Portal   | React + TypeScript     | Schema management, credential issuance, analytics    |
| Verifier Portal | React + TypeScript     | Proof requests, verification, trust framework config |
| AI Agent SDK    | JavaScript, Python, Go | Agent DID creation, delegation, MCP/A2A integration  |

### 2. API Gateway

The API Gateway (Kong or Envoy) provides:

* **Authentication**: API key, OAuth 2.0, DID Auth
* **Rate limiting**: Per-tenant and per-endpoint throttling
* **Load balancing**: Round-robin across service instances
* **WebSocket support**: Real-time event streaming
* **MCP server endpoint**: For AI agent tool access
* **A2A Agent Card serving**: `/.well-known/agent.json`

### 3. Service Layer

#### DID Service

Manages the full lifecycle of Decentralized Identifiers:

* **Create**: Generate key pairs, construct DID Document, register on-chain
* **Resolve**: Fetch DID Document from the ADI blockchain via Universal Resolver
* **Update**: Modify service endpoints, rotate keys, add authentication methods
* **Deactivate**: Permanently deactivate a DID (GDPR right-to-erasure)
* **Key Management**: Ed25519, secp256k1, P-256 key generation and rotation

#### VC Service

Handles the full Verifiable Credential lifecycle:

* **Schema Management**: Define, version, and publish credential schemas
* **Issuance**: Create and sign VCs with issuer's DID
* **Verification**: Check signature, schema compliance, expiry, revocation status
* **Presentation**: Generate and verify Verifiable Presentations
* **Selective Disclosure**: BBS+ based attribute-level disclosure
* **Revocation**: On-chain revocation via Revocation Registry

#### Agent Service

Provides DIDComm v2 messaging infrastructure:

* **Connection Protocol**: Establish pairwise DID connections
* **Credential Offer/Request**: Protocol for issuing and requesting VCs
* **Message Routing**: Cloud agent mediation for offline delivery
* **Encryption**: X25519 key agreement + XChaCha20-Poly1305

#### AI Agent Identity Service

First-class identity for autonomous AI agents:

* **Agent DID Management**: Create/manage `did:adi:agent:*` identifiers
* **Delegation Chains**: Issue scoped delegation VCs (human -> agent -> sub-agent)
* **Capability Tokens (IBCT)**: Generate/verify invocation-bound tokens
* **Trust Scoring**: On-chain reputation from verification history
* **Agent Cards**: A2A-compatible agent metadata publication
* **MCP-I/A2A Integration**: Protocol bridges for AI agent interoperability

### 4. Data Layer

| Store           | Purpose            | Data                                            |
| --------------- | ------------------ | ----------------------------------------------- |
| PostgreSQL      | Off-chain indexing | DID metadata, VC indices, audit logs            |
| Redis           | Caching            | DID resolution cache, session data, rate limits |
| NATS / RabbitMQ | Messaging          | Agent-to-agent messages, event streaming        |

### 5. ADI Blockchain Layer

Four smart contracts form the on-chain trust infrastructure:

| Contract             | Purpose                       | Key Operations                           |
| -------------------- | ----------------------------- | ---------------------------------------- |
| DID Registry         | DID Document registration     | register, resolve, update, deactivate    |
| Schema Registry      | Credential schema definitions | createSchema, getSchema, listSchemas     |
| Revocation Registry  | Credential revocation status  | revoke, isRevoked, batchRevoke           |
| Agent Trust Registry | Agent identity and reputation | registerAgent, updateScore, decommission |

### 6. Decentralized Storage

IPFS (or ADI's native storage layer) stores:

* Full DID Documents (referenced by on-chain hash)
* Credential schema definitions
* Revocation lists (StatusList2021)
* Agent Cards and capability attestations

## Data Flow: Issue and Verify a Credential

```mermaid
sequenceDiagram
    participant Issuer
    participant IDA API
    participant ADI Chain
    participant Holder Wallet
    participant Verifier

    Issuer->>IDA API: POST /vc/issue (schema, claims, holder DID)
    IDA API->>ADI Chain: Verify issuer DID
    IDA API->>ADI Chain: Verify schema exists
    IDA API->>IDA API: Sign VC with issuer key
    IDA API->>Holder Wallet: Deliver VC via DIDComm
    Holder Wallet->>Holder Wallet: Store VC (encrypted)

    Verifier->>Holder Wallet: Request proof (DIDComm / QR)
    Holder Wallet->>Holder Wallet: Create VP (selective disclosure)
    Holder Wallet->>Verifier: Present VP
    Verifier->>IDA API: POST /vc/verify (VP)
    IDA API->>ADI Chain: Check issuer DID, schema, revocation
    IDA API->>Verifier: Verification result
```

## Data Flow: AI Agent Delegation

```mermaid
sequenceDiagram
    participant Human
    participant IDA API
    participant ADI Chain
    participant Agent
    participant Service

    Human->>IDA API: POST /agent/create (capabilities, model)
    IDA API->>ADI Chain: Register agent DID
    IDA API->>Human: Agent DID + Agent Card

    Human->>IDA API: POST /delegation/issue (agent DID, scope)
    IDA API->>IDA API: Create delegation VC + IBCT
    IDA API->>Agent: Deliver delegation VC

    Agent->>Service: Request action + present IBCT
    Service->>IDA API: POST /delegation/verify (IBCT chain)
    IDA API->>ADI Chain: Verify delegation chain + trust score
    IDA API->>Service: Verification result + scope
    Service->>Agent: Action result
```

## Security Architecture

| Layer                | Mechanism                                                       |
| -------------------- | --------------------------------------------------------------- |
| Transport            | TLS 1.3 for all API communications                              |
| Authentication       | DID Auth (challenge-response), OAuth 2.0, API keys              |
| Encryption at rest   | AES-256 for stored credentials and keys                         |
| DIDComm encryption   | X25519 + XChaCha20-Poly1305                                     |
| Key storage (server) | HSM-backed key management                                       |
| Key storage (mobile) | Secure Enclave / TEE                                            |
| Signatures           | Ed25519Signature2020, BBS+ for selective disclosure             |
| Agent tokens         | EdDSA-signed JWT (single-hop), Biscuit with Datalog (multi-hop) |
| Audit                | Immutable, cryptographically signed action logs                 |

## Technology Stack

| Layer           | Technology                    |
| --------------- | ----------------------------- |
| Blockchain      | ADI Chain                     |
| Smart Contracts | Solidity / ADI VM             |
| Backend         | Go / Rust                     |
| API Gateway     | Kong / Envoy                  |
| Message Queue   | NATS / RabbitMQ               |
| Database        | PostgreSQL + Redis            |
| Storage         | IPFS                          |
| Web Portals     | React + TypeScript + Tailwind |
| Mobile Wallet   | React Native / Flutter        |
| Cryptography    | libsodium, BBS+, Biscuit      |
| CI/CD           | GitHub Actions + ArgoCD       |
| Monitoring      | Prometheus + Grafana          |
| Orchestration   | Kubernetes                    |