How it works¶

At a high level there are only a few moving parts: you (using the CLI or the web console), the Blackbook server running in Docker, and its PostgreSQL database — everything encrypted and authenticated between them.

flowchart LR
    subgraph laptop["Your machine"]
        cli["bbk CLI"]
        browser["Web console<br/>(your browser)"]
    end

    subgraph host["Docker host — starts with one command"]
        direction TB
        server["Blackbook server<br/>HTTPS · mutual TLS"]
        db[("PostgreSQL<br/>encrypted at rest")]
        vault["Data volume<br/>master key · CA · certs"]
    end

    browser -->|runs commands locally| cli
    cli -->|"TLS 1.3 + client certificate + token"| server
    server --> db
    server --> vault

• The CLI is how you (or your scripts) actually use Blackbook.
• The web console is an optional local page that simply runs the CLI for you — same commands, nicer buttons.
• The server enforces every rule and does all the encryption. It's the only thing that ever holds the master key (in memory).
• PostgreSQL stores the encrypted data. The data volume holds the keys and certificates. Both live on the Docker host you control.

Storing and reading a secret always passes through the same gates, so you get the same protection every time:

sequenceDiagram
    actor You
    participant CLI as bbk CLI
    participant Server as Blackbook server
    You->>CLI: bbk put api-key "sk_live_..."
    CLI->>Server: store  (mutual TLS + token)
    Note over Server: 1 · Confirm who you are<br/>2 · Confirm you're allowed<br/>3 · Encrypt, then save
    Server-->>You: stored ✓
    You->>CLI: bbk get api-key
    CLI->>Server: read  (mutual TLS + token)
    Note over Server: Same identity + permission checks,<br/>then decrypt and return
    Server-->>You: sk_live_...