# getoptimum/mump2p-cli architecture

> Architecture diagram of the GitHub repository getoptimum/mump2p-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/getoptimum/mump2p-cli
- Repository: https://github.com/getoptimum/mump2p-cli

## Overview

##### Project type and purpose
- This is a standalone CLI tool (“mump2p”) for interacting with the OptimumP2P pub/sub network.
- It is *not* a full-stack web app but rather an open-source command-line utility that:
- Performs JWT-based authentication (device flow)
- Publishes messages to topics
- Subscribes to real-time streams
- Enforces local rate limits and usage tracking
- Persists messages locally and/or forwards them to webhooks

##### File structure
- Top-level:
- `main.go` + `cmd/` directory – command definitions (login, publish, subscribe, usage, version, etc.)
- `internal/auth/` – client, token parsing, storage (JWT handling)
- `internal/ratelimit/` – rate-limit models and enforcement
- `internal/config/` – loading CLI configuration (DOMAIN, CLIENT_ID, SERVICE_URL)
- `scripts/` – helper scripts (e.g., sample message sender)
- `docs/` – user guide

##### Key insights from README
- The CLI calls an external service (OptimumP2P server) over HTTP or WebSocket-like streaming.
- Authentication is token-based; commands must include/refresh JWT.
- Publish and subscribe functionality have optional flags for custom endpoints, persistence paths, and webhook forwarding.

##### Main components and their relationships
a. Components
1. CLI Command Parser (cobra in `cmd/`)
2. Configuration Loader (`internal/config`)
3. Auth Module (`internal/auth`):
– Device-flow login (obtains JWT)
– Token storage & refresh
4. RateLimiter Module (`internal/ratelimit`):
– Local publish count & quota checks
5. Publisher (`cmd/publish.go` + auth & ratelimit)
6. Subscriber (`cmd/subscribe.go` + auth):
– Persistent Storage (local filesystem)
– Webhook Forwarder (async queue + HTTP POST)
7. Usage Reporter (`cmd/usages.go`)
8. External OptimumP2P Service (HTTP/streaming API)
9. Local File System (message persistence)
10. External Webhook Endpoint(s)

b. Relationships & data flow
- User invokes CLI → Command Parser → loads config → ensure valid JWT via Auth Module →
- For publish: RateLimiter checks → HTTP POST to P2P service → report result
- For subscribe: open stream to P2P service → receive messages →
– write to disk (if `--persist`)
– enqueue & POST to webhook (if `--webhook`)
- For usage: HTTP GET to P2P service with JWT → parse & display limits
- Auth Module may call token endpoint to refresh JWT as needed

c. Architectural patterns
- Modular CLI layers (cobra command pattern)
- Separation of concerns: config/auth/rate-limit/modules
- Adapter pattern for persistence and webhook forwarding
- Token-based security

d. Key technologies
- Go’s `cobra` CLI framework
- HTTP client
- JSON Web Tokens (JWT)
- Local file I/O
- Shell scripts for auxiliary tasks

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    CLI["User CLI"]:::external
    Root["CLI Parser"]:::internal
    AuthCmd["Auth Command"]:::internal
    PublishCmd["Publish Command"]:::internal
    SubscribeCmd["Subscribe Command"]:::internal
    UsageCmd["Usage Reporter"]:::internal
    VersionCmd["Version Command"]:::internal
    Main["main.go"]:::internal

    CLI -->|invokes| Root
    Main -->|calls| Root

    Root -->|loads config| Config
    Root --> AuthCmd
    Root --> PublishCmd
    Root --> SubscribeCmd
    Root --> UsageCmd
    Root --> VersionCmd

    %% Core Modules
    subgraph "Core Modules"
        Config["Configuration Loader"]:::internal
        AuthClient["Auth Client"]:::internal
        AuthModels["Auth Models"]:::internal
        AuthStore["Auth Storage"]:::internal
        RateModels["RateLimiter Models"]:::internal
        RateLogic["RateLimiter Logic"]:::internal
    end

    AuthCmd --> AuthClient
    AuthCmd --> AuthStore
    AuthCmd --> AuthModels

    PublishCmd --> AuthClient
    PublishCmd --> RateLogic
    RateLogic --> RateModels
    PublishCmd -->|"HTTP POST /publish"| P2PService

    SubscribeCmd --> AuthClient
    SubscribeCmd -->|"open stream"| P2PService
    SubscribeCmd --> FilePersist
    SubscribeCmd --> Queue

    UsageCmd --> AuthClient
    UsageCmd -->|"HTTP GET /usage"| P2PService

    %% Adapters
    subgraph "Adapters"
        FilePersist["Persistence Adapter"]:::adapter
        Queue["Async Queue"]:::adapter
        WebhookAdapter["Webhook Adapter"]:::adapter
    end

    Queue --> WebhookAdapter
    WebhookAdapter -->|"HTTP POST"| WebhookEP

    FilePersist --> LocalFS

    %% External Services
    subgraph "External Services"
        P2PService["OptimumP2P Service"]:::external
        WebhookEP["Webhook Endpoint(s)"]:::external
        LocalFS["Local File System"]:::external
    end

    %% Click Events
    click Root "https://github.com/getoptimum/mump2p-cli/blob/main/cmd/root.go"
    click AuthCmd "https://github.com/getoptimum/mump2p-cli/blob/main/cmd/auth.go"
    click PublishCmd "https://github.com/getoptimum/mump2p-cli/blob/main/cmd/publish.go"
    click SubscribeCmd "https://github.com/getoptimum/mump2p-cli/blob/main/cmd/subscribe.go"
    click UsageCmd "https://github.com/getoptimum/mump2p-cli/blob/main/cmd/usages.go"
    click VersionCmd "https://github.com/getoptimum/mump2p-cli/blob/main/cmd/version.go"
    click Config "https://github.com/getoptimum/mump2p-cli/blob/main/internal/config/config.go"
    click AuthClient "https://github.com/getoptimum/mump2p-cli/blob/main/internal/auth/client.go"
    click AuthModels "https://github.com/getoptimum/mump2p-cli/blob/main/internal/auth/models.go"
    click AuthModels "https://github.com/getoptimum/mump2p-cli/blob/main/internal/auth/token.go"
    click AuthStore "https://github.com/getoptimum/mump2p-cli/blob/main/internal/auth/storage.go"
    click RateModels "https://github.com/getoptimum/mump2p-cli/blob/main/internal/ratelimit/models.go"
    click RateLogic "https://github.com/getoptimum/mump2p-cli/blob/main/internal/ratelimit/ratelimit.go"
    click Main "https://github.com/getoptimum/mump2p-cli/blob/main/main.go"
    click FilePersist "https://github.com/getoptimum/mump2p-cli/blob/main/scripts/send-messages.sh"
    click WebhookAdapter "https://github.com/getoptimum/mump2p-cli/blob/main/docs/guide.md"
    click P2PService "https://github.com/getoptimum/mump2p-cli/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#6fa8dc,stroke-width:2px
    classDef external fill:#d9ead3,stroke:#93c47d,stroke-width:2px
    classDef adapter fill:#fff2cc,stroke:#ffd966,stroke-width:2px
```
