graph TB
subgraph "External Systems"
BAGS["Bags API<br/>Authentication & Analytics"]
SAID["SAID Identity Gateway<br/>Agent Registry"]
end
subgraph "AgentID Backend"
API["Express API"]
REG["Registration Service"]
VER["Verification Service"]
REP["Reputation Service"]
BAD["Badge Service"]
DB[("PostgreSQL")]
REDIS[("Redis Cache")]
end
subgraph "AgentID Frontend"
UI["Registry UI"]
WIDGET["Embeddable Widget"]
end
BAGS <-->|"Ed25519 Auth"| REG
SAID <-->|"A2A Discovery"| REP
API --> REG
API --> VER
API --> REP
API --> BAD
REG --> DB
VER --> DB
REP --> DB
BAD --> DB
BAD --> REDIS
UI --> API
WIDGET --> API

sequenceDiagram
participant Dev as "Developer"
participant API as "AgentID API"
participant BAGS as "Bags API"
participant SAID as "SAID Gateway"
participant DB as "PostgreSQL"
Dev->>API: POST /register
API->>API: validateRegistrationInput()
API->>API: verifyBagsSignature()
API->>BAGS: POST /agent/v2/auth/init
BAGS-->>API: {message, nonce}
API->>BAGS: POST /agent/v2/auth/callback
BAGS-->>API: {apiKeyId}
API->>SAID: POST /agents/register
SAID-->>API: {result}
API->>DB: INSERT agent_identities
DB-->>API: {created agent}
API-->>Dev: 201 {agent, said}

sequenceDiagram
participant App as "Bags App"
participant API as "AgentID API"
participant PKI as "PKI Challenge"
participant DB as "PostgreSQL"
App->>API: POST /verify/challenge
API->>PKI: issueChallenge(pubkey)
PKI->>DB: INSERT agent_verifications
DB-->>PKI: {verification}
PKI-->>API: {nonce, challenge, expiresIn}
API-->>App: 200 {nonce, challenge, expiresIn}
App->>API: POST /verify/response
API->>PKI: verifyChallenge(pubkey, nonce, signature)
PKI->>DB: SELECT verification
DB-->>PKI: {verification}
PKI->>PKI: verify Ed25519 signature
PKI->>DB: UPDATE completed=true
PKI->>DB: UPDATE last_verified
PKI-->>API: {verified, pubkey, timestamp}
API-->>App: 200 {verified, ...}

flowchart TD
Start(["GET /badge/:pubkey"]) --> CacheCheck["Check Redis Cache"]
CacheCheck -->|Hit| ReturnCached["Return Cached JSON"]
CacheCheck -->|Miss| LoadAgent["Load Agent from DB"]
LoadAgent --> ComputeRep["Compute Reputation"]
ComputeRep --> LoadActions["Load Action Stats"]
LoadActions --> BuildBadge["Build Badge JSON"]
BuildBadge --> CacheStore["Store in Redis"]
CacheStore --> ReturnBadge["Return Badge JSON"]
ReturnCached --> End([End])
ReturnBadge --> End