# DCRouter Storage Overview

DCRouter uses two complementary storage systems: **StorageManager** for configuration and state, and **CacheDb** for time-limited cached data.

## StorageManager (Key-Value Store)

A lightweight, pluggable key-value store for configuration, credentials, and runtime state. Data is persisted as flat JSON files on disk by default.

### Default Path

```
~/.serve.zone/dcrouter/storage/
```

Configurable via `options.storage.fsPath` or `options.baseDir`.

### Backends

```typescript
// Filesystem (default)
storage: { fsPath: '/var/lib/dcrouter/data' }

// Custom (Redis, S3, etc.)
storage: {
  readFunction: async (key) => await redis.get(key),
  writeFunction: async (key, value) => await redis.set(key, value),
}

// In-memory (omit storage config — data lost on restart)
```

### What's Stored

| Prefix | Contents | Managed By |
|--------|----------|------------|
| `/vpn/server-keys` | VPN server Noise + WireGuard keypairs | `VpnManager` |
| `/vpn/clients/{clientId}` | VPN client registrations (keys, tags, description, assigned IP) | `VpnManager` |
| `/config-api/routes/{uuid}.json` | Programmatic routes (created via OpsServer API) | `RouteConfigManager` |
| `/config-api/tokens/{uuid}.json` | API tokens (hashed secrets, scopes, expiry) | `ApiTokenManager` |
| `/config-api/overrides/{routeName}.json` | Hardcoded route overrides (enable/disable) | `RouteConfigManager` |
| `/email/bounces/suppression-list.json` | Email bounce suppression list | `smartmta` |
| `/certs/*` | TLS certificates and ACME state | `SmartAcme` (via `StorageBackedCertManager`) |

### API

```typescript
// Read/write JSON
await storageManager.getJSON<T>(key);
await storageManager.setJSON(key, value);

// Raw string read/write
await storageManager.get(key);
await storageManager.set(key, value);

// List keys by prefix
await storageManager.list('/vpn/clients/');

// Delete
await storageManager.delete(key);
```

## CacheDb (Embedded MongoDB)

An embedded MongoDB-compatible database (via `@push.rocks/smartdb` + `@push.rocks/smartdata`) for cached data with automatic TTL-based cleanup.

### Default Path

```
~/.serve.zone/dcrouter/tsmdb/
```

Configurable via `options.cacheConfig.storagePath`.

### What's Cached

| Document Type | Default TTL | Purpose |
|--------------|-------------|---------|
| `CachedEmail` | 30 days | Email metadata cache for dashboard display |
| `CachedIPReputation` | 1 day | IP reputation lookup results (DNSBL checks) |

### Configuration

```typescript
cacheConfig: {
  enabled: true,                                    // default: true
  storagePath: '~/.serve.zone/dcrouter/tsmdb',     // default
  dbName: 'dcrouter',                               // default
  cleanupIntervalHours: 1,                          // how often to purge expired records
  ttlConfig: {
    emails: 30,          // days
    ipReputation: 1,     // days
    bounces: 30,         // days (reserved)
    dkimKeys: 90,        // days (reserved)
    suppression: 30,     // days (reserved)
  },
}
```

### How It Works

1. `CacheDb` starts a `LocalSmartDb` instance (embedded MongoDB process)
2. `smartdata` connects to it via Unix socket
3. Document classes (`CachedEmail`, `CachedIPReputation`) are decorated with `@Collection` and use `smartdata` ORM
4. `CacheCleaner` runs on a timer, purging records older than their configured TTL

### Disabling

For development or lightweight deployments, disable the cache to avoid starting a MongoDB process:

```typescript
cacheConfig: { enabled: false }
```

## When to Use Which

| Use Case | System | Why |
|----------|--------|-----|
| VPN keys, API tokens, routes, certs | **StorageManager** | Small JSON blobs, key-value access, no queries needed |
| Email metadata, IP reputation | **CacheDb** | Time-series data, TTL expiry, potential for queries/aggregation |
| Runtime state (connected clients, metrics) | **Neither** | In-memory only, rebuilt on startup |