# Architecture Overview

## System Components

```
┌─────────────────────────────────────────────────────────────────┐
│                       Network Clients                            │
│  (IoT Devices, Laptops, Phones with WPA-Enterprise credentials) │
└──────────────────────┬──────────────────────────────────────────┘
                       │ RADIUS Access-Request
                       │ (MAC, Username, EAP)
                       ▼
┌─────────────────────────────────────────────────────────────────┐
│                    FreeRADIUS Server                             │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ EAP Module (Password/Certificate Verification)             │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
│                             ▼                                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ device_manager_radius.py (rlm_python)                      │ │
│  │                                                             │ │
│  │ • Parse RADIUS attributes (MAC, Username, NAS, SSID)       │ │
│  │ • Call Frappe API for authorization decision               │ │
│  │ • Cache credentials in SQLite for offline operation        │ │
│  │ • Return VLAN assignment and reply attributes              │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
│                             │                                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ SQLite Credential Cache                                    │ │
│  │ /var/lib/freeradius/device_manager_verifier_cache.sqlite3  │ │
│  │                                                             │ │
│  │ • Stores SSHA password hashes (no plaintext)               │ │
│  │ • Device-specific VLAN assignments                         │ │
│  │ • Expiration timestamps                                    │ │
│  │ • Used when Frappe unreachable                             │ │
│  └────────────────────────────────────────────────────────────┘ │
└──────────────────────────┬──────────────────────────────────────┘
                           │ HTTP POST with API token
                           │ /api/method/device_manager.api.radius_authorize
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                     Frappe Server                                │
│                                                                  │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ device_manager.api.radius_authorize()                      │ │
│  │                                                             │ │
│  │ • Authenticate API token                                   │ │
│  │ • Find device by MAC address                               │ │
│  │ • Evaluate access policy                                   │ │
│  │ • Create audit records                                     │ │
│  │ • Return decision with VLAN and credentials                │ │
│  └──────────────────────────┬─────────────────────────────────┘ │
│                             │                                    │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │ MariaDB/PostgreSQL Database                                │ │
│  │                                                             │ │
│  │ • DM Device (registered devices)                           │ │
│  │ • DM Access Policy (authorization rules)                   │ │
│  │ • DM Network Segment (VLAN mappings)                       │ │
│  │ • DM Radius Auth Event (audit log)                         │ │
│  │ • DM Access Decision (decision log)                        │ │
│  │ • DM Device Audit Event (compliance log)                   │ │
│  │ • Stored Credential Verifier (password hashes)             │ │
│  └────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```

## Data Flow

### 1. Normal Operation (Frappe Reachable)

```
Client → FreeRADIUS → device_manager_radius.py
                            │
                            ├─→ HTTP API call to Frappe
                            │   POST /api/method/device_manager.api.radius_authorize
                            │   Authorization: token API_KEY:API_SECRET
                            │
                            │   Request payload:
                            │   - calling_station_id (MAC)
                            │   - username
                            │   - nas_identifier
                            │   - nas_ip_address
                            │   - ssid
                            │   - raw_request (full RADIUS attributes)
                            │
                            ├─← Response from Frappe
                            │   {
                            │     "event": "AUTH-001",
                            │     "decision": "DEC-001",
                            │     "result": "Allow",
                            │     "vlan_id": 100,
                            │     "radius_reply_attributes": {...},
                            │     "cacheable_credentials": {
                            │       "username": "device001",
                            │       "control_attributes": {
                            │         "SSHA-Password": "base64hash"
                            │       }
                            │     }
                            │   }
                            │
                            ├─→ Cache decision in SQLite
                            │
                            └─→ Return to FreeRADIUS
                                - RADIUS reply attributes (VLAN)
                                - Control attributes (password hash)
                                - Accept/Reject decision

Client ← FreeRADIUS ← Access-Accept + VLAN assignment
```

### 2. Offline Operation (Frappe Unreachable)

```
Client → FreeRADIUS → device_manager_radius.py
                            │
                            ├─→ HTTP API call to Frappe (FAILS)
                            │   Network error / Timeout
                            │
                            ├─→ Query SQLite cache
                            │   SELECT * FROM radius_verifier_cache
                            │   WHERE username = ?
                            │
                            ├─← Cached decision found
                            │   {
                            │     "result": "Allow",
                            │     "vlan_id": 100,
                            │     "control_attributes": {
                            │       "SSHA-Password": "base64hash"
                            │     },
                            │     "from_cache": true
                            │   }
                            │
                            └─→ Return to FreeRADIUS
                                - RADIUS reply from cache
                                - Control attributes from cache
                                - Accept with cached VLAN

Client ← FreeRADIUS ← Access-Accept (from cache)
```

## Deployment Modes Comparison

### Mode 1: Standalone Client (NEW)

**Use Case:** FreeRADIUS on dedicated appliance, Frappe on app server

```
┌─────────────────┐     API over HTTPS      ┌─────────────────┐
│ RADIUS Server   │ ←──────────────────────→ │ Frappe Server   │
│                 │                          │                 │
│ • FreeRADIUS    │                          │ • Frappe        │
│ • Python 3.10+  │                          │ • device_mgr    │
│ • device_mgr_   │                          │ • MariaDB       │
│   radius.py     │                          │                 │
│ • SQLite cache  │                          │                 │
└─────────────────┘                          └─────────────────┘

Dependencies: Python stdlib only
Module: device_manager_radius
Config: DEVICE_MANAGER_FRAPPE_URL + API credentials
```

### Mode 2: Local (Integrated)

**Use Case:** Everything on one server (lab/testing)

```
┌──────────────────────────────────┐
│ Single Server                    │
│                                  │
│ • FreeRADIUS                     │
│ • Frappe bench                   │
│ • device_manager app             │
│ • MariaDB                        │
│                                  │
│ In-process import:               │
│ device_manager.freeradius        │
│ ↓ calls ↓                        │
│ device_manager.radius            │
│ ↓ queries ↓                      │
│ Database                         │
└──────────────────────────────────┘

Dependencies: Full Frappe + device_manager
Module: device_manager.freeradius
Config: DEVICE_MANAGER_BENCH_PATH + SITE
```

### Mode 3: Remote (Full App Installed)

**Use Case:** RADIUS server with device_manager installed, Frappe remote

```
┌─────────────────┐     API over HTTPS      ┌─────────────────┐
│ RADIUS Server   │ ←──────────────────────→ │ Frappe Server   │
│                 │                          │                 │
│ • FreeRADIUS    │                          │ • Frappe        │
│ • Python 3.10+  │                          │ • device_mgr    │
│ • device_mgr    │                          │ • MariaDB       │
│   app (full)    │                          │                 │
│ • SQLite cache  │                          │                 │
└─────────────────┘                          └─────────────────┘

Dependencies: device_manager package
Module: device_manager.freeradius
Config: DEVICE_MANAGER_FRAPPE_URL + API credentials
```

## Security Architecture

### Authentication Flow

```
1. FreeRADIUS validates device credentials (EAP-PEAP/TLS)
   └─→ If valid, call device_manager_radius

2. device_manager_radius calls Frappe API
   ├─→ Authorization: token API_KEY:API_SECRET
   ├─→ HTTPS encrypted transport
   └─→ Token validated by Frappe

3. Frappe evaluates device policy
   ├─→ Lookup device by MAC address
   ├─→ Check approval status
   ├─→ Check lifecycle state
   ├─→ Evaluate access policy rules
   └─→ Determine VLAN assignment

4. Response cached locally (if cacheable)
   ├─→ Only SSHA hashes stored (no plaintext)
   ├─→ Cache file owned by freerad user
   ├─→ Optional expiration date
   └─→ Used only when Frappe unreachable
```

### Secret Management

| Secret Type | Storage Location | Access Control |
|-------------|------------------|----------------|
| Device passwords | Never stored plaintext | N/A |
| SSHA verifiers | SQLite cache + Frappe DB | freerad user, DB permissions |
| API credentials | systemd override | root:root 600 |
| Frappe session tokens | Frappe DB | System Manager only |

## Performance Characteristics

| Operation | Typical Latency | Notes |
|-----------|----------------|-------|
| Cache hit | < 5ms | SQLite query |
| API call (LAN) | 10-50ms | Network + DB query |
| API call (WAN) | 50-500ms | Depends on network |
| API timeout | 2.5s (default) | Configurable |
| Cache write | < 10ms | SQLite insert |

## Scalability

### Single RADIUS Server
- Handles 1000+ auth/sec with cache hits
- ~100 auth/sec with API calls (network bound)
- SQLite cache suitable for <100k devices

### High Availability
- Deploy multiple RADIUS servers (round-robin DNS or load balancer)
- Each server maintains independent SQLite cache
- Shared Frappe backend ensures consistent policy
- Consider Redis cache for distributed deployment (future enhancement)

## Monitoring Points

### RADIUS Server
- FreeRADIUS logs (`radiusd.L_INFO`, `radiusd.L_ERR`)
- Cache hit rate (grep logs for "using cached credentials")
- API timeout rate (grep logs for "authorization failed")
- Cache size (SQLite table row count)

### Frappe Server
- API endpoint latency (Frappe request logs)
- Authentication success/failure rate
- Policy evaluation time
- Audit log growth rate

### Network
- HTTPS latency between RADIUS and Frappe
- Packet loss between clients and RADIUS
- Certificate expiration monitoring