# Onebox Project Hints

## SSL Certificate Storage (NodeNext/SmartDB)

SSL certificates are stored directly in SmartDB as PEM content instead of file paths:

- `ISslCertificate` and `ICertificate` interfaces use `certPem`, `keyPem`, `fullchainPem` properties
- No filesystem storage for certificates - everything in DB
- `reverseproxy.ts` reads certificate PEM content from database
- `certmanager.ts` stores SmartACME certificates directly to database

## Architecture Notes

### Database Layer

The database layer is SmartDB/SmartData-backed. `OneboxDatabase` owns document classes and current startup migrations.

**Directory Structure:**

```
ts/database/
├── index.ts              # Main OneboxDatabase class
├── docs.ts               # SmartData document classes
└── secret-settings.ts    # Secret settings manager
```

**Import paths:**

- Main: `import { OneboxDatabase } from './database/index.js'`

**API Compatibility:**

- The `OneboxDatabase` class maintains the same public API
- Backend code works with SmartData document instances directly

## Current Startup Migrations

- `valkey-platform-rename` renames legacy Redis platform data and records completion in metadata
- `coretraffic-platform-rename` renames persisted proxy platform data and records completion in metadata

## Reverse Proxy (CoreTraffic Docker Service)

The reverse proxy uses **CoreTraffic** running as a Docker Swarm service for production-grade reverse proxying with TLS termination and WebSocket handling.

**Architecture:**

- CoreTraffic runs as Docker Swarm service (`onebox-coretraffic`) on the overlay network
- No host binary download required - uses `code.foss.global/serve.zone/coretraffic:latest`
- Routes are pushed dynamically via the CoreTraffic admin API (host port 2019)
- Automatic HTTPS disabled - certificates managed externally via SmartACME
- Zero-downtime configuration updates
- Services reached by Docker service name (e.g., `onebox-hello-world:80`)

**Key files:**

- `ts/classes/coretraffic.ts` - CoreTrafficManager class for Docker service and Admin API
- `ts/classes/reverseproxy.ts` - Delegates to CoreTrafficManager

**Certificate workflow:**

1. `CertRequirementManager` creates requirements for domains
2. Daemon processes requirements via `certmanager.ts`
3. Certificates stored in database (PEM content)
4. `reverseProxy.addCertificate()` passes PEM content to CoreTraffic route config
5. CoreTraffic serves TLS with the loaded certificates (no volume mounts needed)

**Docker Service Configuration:**

- Service name: `onebox-coretraffic`
- Image: `code.foss.global/serve.zone/coretraffic:latest`
- Network: `onebox-network` (overlay, attachable)
- Startup: CoreTraffic admin API listens on container port 3000, published on host port 2019

**Port Mapping:**

- Dev mode: HTTP on 8080, HTTPS on 8443, Admin on 2019
- Production: HTTP on 80, HTTPS on 443, Admin on 2019
- All ports use `PublishMode: 'host'` for direct binding

**Log Receiver:**

- `ProxyLogReceiver` remains the host-side access-log stream endpoint for proxy log integrations
