# API Key Management System Architecture

## System Overview

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           API Key Management System                             │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐  │
│   │   CLI       │     │   HTTP API  │     │   Service   │     │   External  │  │
│   │   Layer     │────▶│   Layer     │────▶│   Layer     │────▶│   Services  │  │
│   └─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘  │
│          │                   │                   │                   │          │
│          │                   │                   │                   │          │
│          ▼                   ▼                   ▼                   ▼          │
│   ┌─────────────────────────────────────────────────────────────────────────┐   │
│   │                         Core Modules                                     │   │
│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │   │
│   │  │ Service │ │Validator│ │ Anomaly │ │Rotation │ │ Cleanup │          │   │
│   │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘          │   │
│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │   │
│   │  │ Webhook │ │Encrypt  │ │Blacklist│ │ Report  │ │  Error  │          │   │
│   │  └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘          │   │
│   └─────────────────────────────────────────────────────────────────────────┘   │
│          │                   │                   │                              │
│          ▼                   ▼                   ▼                              │
│   ┌─────────────┐     ┌─────────────┐     ┌─────────────┐                      │
│   │  PostgreSQL │     │    Redis    │     │   External  │                      │
│   │  (Storage)  │     │   (Cache)   │     │  (Gitea/n8n)│                      │
│   └─────────────┘     └─────────────┘     └─────────────┘                      │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
```

## Module Dependencies

```
                    ┌──────────────┐
                    │   models.rs  │
                    │  (Types)     │
                    └──────┬───────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│  service.rs   │  │   error.rs    │  │  validator.rs │
│  (Core CRUD)  │  │  (Errors)     │  │  (Cache+Rate) │
└───────┬───────┘  └───────────────┘  └───────────────┘
        │
        │         ┌───────────────────────────────┐
        │         │                               │
        ▼         ▼                               ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│  anomaly.rs   │  │  rotation.rs  │  │  blacklist.rs │
│  (Detection)  │  │  (Rotation)   │  │  (IP Block)   │
└───────────────┘  └───────────────┘  └───────────────┘
```

## Request Flow

```
Client Request
      │
      ▼
┌─────────────┐
│   CLI/API   │
└──────┬──────┘
       │
       ▼
┌─────────────┐     ┌─────────────┐
│  Rate Limit │────▶│  IP Blacklist│
│  Check      │     │  Check      │
└──────┬──────┘     └──────┬──────┘
       │                   │
       └─────────┬─────────┘
                 │
                 ▼
         ┌───────────────┐
         │  Hash API Key │
         └───────┬───────┘
                 │
                 ▼
         ┌───────────────┐     ┌───────────────┐
         │  Cache Lookup │────▶│  PostgreSQL   │
         └───────┬───────┘     │  Lookup       │
                 │             └───────┬───────┘
                 │                     │
                 └──────────┬──────────┘
                            │
                            ▼
                    ┌───────────────┐
                    │  Validate    │
                    │  (Status,    │
                    │   Expiry)    │
                    └───────┬───────┘
                            │
              ┌─────────────┼─────────────┐
              │             │             │
              ▼             ▼             ▼
        ┌──────────┐  ┌──────────┐  ┌──────────┐
        │  Valid   │  │ Invalid  │  │  Error   │
        │  Response│  │ Response │  │ Response │
        └──────────┘  └──────────┘  └──────────┘
```

## Database Schema

```
┌─────────────────────────────────────────────────────────────────┐
│                          PostgreSQL                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────┐      ┌─────────────────┐                   │
│  │   api_keys      │      │ api_key_audit_  │                   │
│  ├─────────────────┤      │ log             │                   │
│  │ id              │      ├─────────────────┤                   │
│  │ key_id          │─────▶│ id              │                   │
│  │ key_hash        │      │ key_id (FK)     │                   │
│  │ name            │      │ action          │                   │
│  │ key_type        │      │ ip_address      │                   │
│  │ status          │      │ details         │                   │
│  │ expires_at      │      └─────────────────┘                   │
│  │ ...             │                                            │
│  └─────────────────┘      ┌─────────────────┐                   │
│                           │ api_key_anomalies│                  │
│  ┌─────────────────┐      ├─────────────────┤                   │
│  │ gitea_tokens    │      │ id              │                   │
│  ├─────────────────┤      │ key_id (FK)     │                   │
│  │ id              │      │ anomaly_type    │                   │
│  │ gitea_token_id  │      │ severity        │                   │
│  │ token_name      │      │ details         │                   │
│  │ scopes          │      └─────────────────┘                   │
│  └─────────────────┘                                            │
│                                                                 │
│  ┌─────────────────┐                                            │
│  │ n8n_api_keys    │                                            │
│  ├─────────────────┤                                            │
│  │ id              │                                            │
│  │ n8n_key_id      │                                            │
│  │ label           │                                            │
│  └─────────────────┘                                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## External Integrations

```
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           External Integrations                                  │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   ┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐  │
│   │     Gitea       │         │       n8n       │         │     Webhook     │  │
│   ├─────────────────┤         ├─────────────────┤         ├─────────────────┤  │
│   │ • Create Token  │         │ • Create API Key│         │ • Key Created   │  │
│   │ • List Tokens   │         │ • List API Keys │         │ • Key Revoked   │  │
│   │ • Delete Token  │         │ • Delete API Key│         │ • Anomaly       │  │
│   │ • Verify Token  │         │ • Verify        │         │ • Rate Limited  │  │
│   └─────────────────┘         └─────────────────┘         └─────────────────┘  │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘
```

## Security Layers

```
┌─────────────────────────────────────────────────────────────────┐
│                       Security Layers                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Layer 1: Network                                               │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ • IP Blacklist                                          │   │
│  │ • Rate Limiting                                         │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Layer 2: Authentication                                        │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ • API Key Hash (SHA256)                                 │   │
│  │ • Constant-time Comparison                              │   │
│  │ • Key Validation (Status, Expiry)                       │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Layer 3: Monitoring                                            │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ • Anomaly Detection                                     │   │
│  │ • Audit Logging (Encrypted)                             │   │
│  │ • Webhook Notifications                                 │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```