June System Architecture

June is a high-throughput, security-hardened Discord utility and intelligence platform engineered on Node.js 22 LTS and Discord.js v14. It is architected for zero-trust operational security, low-latency persistence using native SQLite with Write-Ahead Logging (WAL), and real-time event streaming for disposable messaging and intelligence workflows.

---

High-Level Topology

The system comprises four primary planes:

1. Ingestion & Gateway Plane: Manages Discord's sharded WebSocket connections, interaction routing, whitelist authorization, and sliding-window rate limiting.
2. Core Execution Plane: Dispatches slash commands, context menus, media forensics, and temporary mailbox workflows.
3. Persistence Plane: Operates Node 22 native SQLite (node:sqlite) in WAL mode alongside an in-memory write-through cache for hot access keys.
4. Web & Realtime Plane: Express 5.x REST API hosting the obsidian dashboard (june.4ofl.dev), Server-Sent Events (SSE) streaming, and Stalwart mail hooks.

flowchart TD
    subgraph Discord ["Discord Cloud"]
        GW["Discord Gateway / REST API"]
        Users["Discord Clients & Guilds"]
    end

    subgraph Host ["June Core Host (Node 22 LTS)"]
        direction TB
        
        subgraph Ingestion ["Ingestion & Gateway Plane"]
            DJS["Discord.js v14 Gateway Client"]
            AuthGuard["Whitelist & Permissions Guard"]
            RateLimit["Sliding Window Rate Limiter"]
        end

        subgraph Execution ["Execution Plane"]
            Router["Command / Interaction Router"]
            WorkerSandbox["Node.js Worker Thread Sandbox (500ms Timeout)"]
            SSRF["SSRF Defense Firewall (RFC 1918 & IPv6)"]
            MediaProcessor["Media Buffer & Forensics Processor"]
        end

        subgraph Persistence ["Persistence Plane"]
            SQLite[("Native node:sqlite (WAL Mode)")]
            Cache["In-Memory Write-Through Cache"]
        end

        subgraph WebPlane ["Web & Realtime Plane"]
            Express["Express 5.x REST API"]
            SSE["Server-Sent Events (SSE) Stream"]
            Dashboard["Obsidian Web Dashboard"]
        end
    end

    subgraph External ["External Services"]
        Stalwart["Stalwart Mail Server (RFC 8620 JMAP)"]
        TempDomain["temp.4ofl.dev SMTP/MX"]
        ExtWeb["External Public Endpoints"]
    end

    Users <--> GW
    GW <--> DJS
    DJS --> AuthGuard --> RateLimit --> Router
    Router --> WorkerSandbox
    Router --> SSRF
    Router --> MediaProcessor
    Router <--> Cache
    Cache <--> SQLite
    
    SSRF -.->|Pinned Socket Connection| ExtWeb
    
    TempDomain --> Stalwart
    Stalwart -->|JMAP Protocol / Push| Express
    Express --> SSE
    SSE --> Dashboard
    Express <--> SQLite

---

Architectural Principles

1. Minimal Footprint, Predictable Concurrency

• Node.js 22 Native SQLite: Unlike bots relying on external C++ npm modules (better-sqlite3) that risk native compilation errors during Node engine upgrades, June leverages Node 22's built-in node:sqlite module.
• Resource Management: Operates at a baseline heap memory footprint of approximately ~100–150MB under idle and standard utility workloads. The production Docker container specifies a 1.5GB memory limit to comfortably accommodate transient media decompression buffers, OCR payloads, and isolated worker threads without out-of-memory thrashing.
• Sub-Millisecond Persistence: In WAL mode, internal SQLite prepared statements execute with sub-millisecond local query latencies. Overall interaction turnaround time is primarily governed by Discord API network round-trips.

2. Multi-Layer Defense in Depth

• Strict SSRF Perimeter: Commands accepting user-supplied URLs or network hosts route through an IP-level firewall that validates both IPv4 and IPv6 addresses against private, link-local, and reserved ranges. Socket connections are pinned directly to validated IPs to eliminate DNS rebinding / TOCTOU vulnerabilities.
• Thread-Level Isolation for ReDoS: Catastrophic regular expression backtracking is mitigated by isolating dynamic pattern matching inside Node.js worker_threads with strict input length limits ($\le 256$ chars pattern, $\le 8,000$ chars input) and a 500ms software watchdog timer (worker.terminate()).

3. Ephemeral Mailbox Lifecycle

• Deterministic 60-Minute Leases: Ephemeral mailboxes provisioned via Stalwart JMAP carry a deterministic 60-minute Time-To-Live (TTL) lease in SQLite. When a lease expires, June severs the local user binding, ensuring disposable addresses cannot be hijacked.

---

Interaction Lifecycle Pipeline

When a user triggers an interaction via Discord (slash command or message context menu):

sequenceDiagram
    autonumber
    actor User as Discord User
    participant GW as Discord Gateway
    participant Core as June Gateway
    participant Guard as Auth & Rate Limiter
    participant Exec as Command Handler
    participant DB as SQLite WAL
    participant API as Discord REST

    User->>GW: Trigger /command
    GW->>Core: InteractionCreate Event
    Core->>Guard: Verify Whitelist & Quotas
    alt Rate Limited or Unauthorized
        Guard-->>GW: Ephemeral Rejection
    else Authorized
        Guard->>Exec: Dispatch Command Context
        Exec->>DB: Query / Mutate State (Write-Through Cache)
        DB-->>Exec: Return Indexed Record
        Exec->>API: Defer / Edit Reply (Embed + Components)
        API-->>User: Render Obsidian Discord Component
    end

1. Gateway Ingestion: The interaction event arrives over Discord's WebSocket connection and is parsed by discord.js.
2. Authorization & Rate-Limiting: Guild and user IDs are validated against June's in-memory whitelist. Sliding-window quotas protect against command abuse.
3. Execution Routing: The interaction is dispatched to its dedicated command module (src/commands/*).
4. Data Access: If state is required, queries hit the SQLite database via prepared statements or the in-memory write-through cache.
5. UI Rendering: Structured response containers are compiled with June's obsidian theme palette (#020202, #10b981) and dispatched via Discord's REST API.

---

Component Specifications

Component	Technology	Role
Runtime	Node.js 22 LTS (CommonJS & ESM)	Core asynchronous runtime with native V8 engine
Discord Interface	Discord.js v14	Gateway WebSocket client, interaction router, component builder
Database Engine	Native node:sqlite (DatabaseSync)	Zero-dependency persistence with Write-Ahead Logging (WAL) and write-through cache
Web Server	Express 5.x REST API	Dashboard backend, OAuth2 authentication, Server-Sent Events (SSE)
Mail Infrastructure	Stalwart Mail Server (RFC 8620 JMAP)	Ephemeral inbox generation & inbound email parsing via HTTPS
Text Recognition	OCR.space API & Buffer Guards	Upstream OCR text extraction with size limits and execution timeouts
Frontend UI	Vanilla CSS / VitePress / Space Grotesk	Obsidian technical documentation and web dashboard