# stamusnetworks/stamusctl architecture

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

- Interactive diagram: https://gitdiagram.com/stamusnetworks/stamusctl
- Repository: https://github.com/stamusnetworks/stamusctl

## Overview

##### Project Type and Purpose
- This is primarily a Go-based CLI application (“stamusctl”) with an optional companion daemon (“stamusd”) exposing a REST API.
- It’s not a web front-end but rather a systems tool that manages containerized Stamus NDR stacks via Docker Compose and a template system.

##### File Structure Analysis
- Top level:
- cmd/ctl – the Cobra-based CLI commands (“compose”, “config”, “template”, “login”, etc.).
- cmd/daemon – Gin-based REST API server code (“stamusd run”, version, docs).
- internal/ – core business logic packaged by domain (“handlers”, “models”, “docker-compose”, “docker”, “logging”, “auth”, “stamus”, “embeds”).
- pkg/ – public helper libraries (mocking, daemon helpers).
- .test/ – end-to-end and unit test inputs & outputs for compose/init.
- docker/, .github/, scripts/, Makefile – build, CI, Dockerfiles for CLI/daemon.
- The separation (cmd vs. internal vs. pkg) follows a typical Go clean-architecture, with command plumbing in cmd/ and logic in internal/.

##### README Insights
- Core responsibilities:
- Template Consumer: loads Go templates from an external repo.
- Docker Compose Wrapper: generates, updates, and drives Docker Compose stacks.
- PCAP Reader: built-in packet capture analysis.
- Registry Connector: login/pull images from container registries.
- Daemon (stamusd): same functions over HTTP (Swagger documented).

##### Diagramming the Architecture
a. Main Components
- CLI Client (stamusctl)
- Daemon Server (stamusd)
- Internal Logic (handlers, models, utils, docker connectors)
- Template System (external stamusctl-templates repo + embedded defaults)
- Docker Engine & Docker Compose
- Containerized Services (Suricata, Logstash, Nginx, etc. as defined by templates)
- Registry (public/private container registries)
- File System (configuration directory, values.yaml, binds)
b. Relationships & Data Flows
1. User invokes `stamusctl` → Cobra CLI parses flags → calls internal handlers.
2. Handlers consult models & utils → load templates (local embed or external repo/registry).
3. Template consumer writes config files (Docker Compose YAML, Nginx conf, apps).
4. Handlers call Docker Compose wrapper (via Go Docker SDK or shell) → Docker Engine → spin up containers.
5. For `readpcap`, handlers invoke built-in PCAP reader module (internal/app).
6. For `login` and `pull`, handlers call Docker registry module (internal/docker).
7. `stamusd` sits behind Gin router, exposes same handler functions over HTTP.
c. Architectural Patterns
- Clean-architecture: cmd → handlers → models → lower-level Docker and template services.
- Separation of Concerns: CLI vs. Daemon vs. Template engine vs. Docker integration.
- Embedded resources: default templates embedded under internal/embeds.
- Dependency Injection: internal/docker uses mocks for unit testing.
d. Key Technologies
- Go, Cobra (CLI), Gin (REST API)
- Go templates + Sprig
- Docker SDK / Docker Compose
- Swagger (for API docs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface Layer
    subgraph "User Interface Layer"
        CLI["CLI Client (stamusctl)"]:::cli
        HTTP["HTTP API Server (stamusd)"]:::api
    end

    CLI -->|"invoke stamusctl"| Main
    HTTP -->|"HTTP request"| Handlers

    %% Command Entrypoint and CLI Commands
    Main["Command Entrypoint (cmd/main.go)"]:::cli
    subgraph "Cobra Commands"
        ComposeCmd["compose"]:::cli
        ConfigCmd["config"]:::cli
        TemplateCmd["template"]:::cli
        LoginCmd["login"]:::cli
        VersionCmd["version"]:::cli
    end
    Main -->|"dispatch command"| ComposeCmd
    Main -->|"dispatch command"| ConfigCmd
    Main -->|"dispatch command"| TemplateCmd
    Main -->|"dispatch command"| LoginCmd
    Main -->|"dispatch command"| VersionCmd

    %% Core Logic Layer
    subgraph "Core Logic Layer"
        Handlers["Handlers"]:::logic
        Models["Domain Models"]:::logic
        Auth["Authentication"]:::logic
        Logging["Logging & Tracing"]:::logic
        Utils["General Utilities"]:::logic
        App["App Mode & Version"]:::logic
    end

    ComposeCmd -->|"call handlers"| Handlers
    ConfigCmd -->|"call handlers"| Handlers
    TemplateCmd -->|"call handlers"| Handlers
    LoginCmd -->|"call handlers"| Handlers
    VersionCmd -->|"call handlers"| Handlers

    Handlers -->|"use models"| Models
    Handlers -->|"authenticate"| Auth
    Handlers -->|"log events"| Logging
    Handlers -->|"util ops"| Utils
    Handlers -->|"read pcap"| App

    %% Template System
    subgraph "Template System"
        Embeds["Embedded Default Templates"]:::tpl
        ExtRepo["External Template Repo"]:::external
    end
    Handlers -->|"load templates"| Embeds
    Handlers -->|"load templates"| ExtRepo

    %% Configuration & File System
    FS["File System (config dir, values.yaml)"]:::infra
    Handlers -->|"write compose & config files"| FS

    %% Docker Orchestration
    subgraph "Docker Orchestration"
        ComposeSvc["Docker Compose Wrapper"]:::infra
        DockerEngine["Docker Engine"]:::infra
        Containers["Containerized Services"]:::infra
    end
    Handlers -->|"generate compose file"| ComposeSvc
    ComposeSvc -->|"invoke Docker API"| DockerEngine
    DockerEngine -->|"runs containers"| Containers

    %% Docker SDK & Registry
    DockerSvc["Docker SDK & Registry Connector"]:::infra
    Registry["Container Registry"]:::external
    Handlers -->|"login/pull images"| DockerSvc
    DockerSvc -->|"pull images"| Registry

    %% API Server Handlers
    HTTP -->|"Gin router"| Handlers

    %% Testing and CI/CD
    E2E["Test Harness (.test)"]:::external
    CI["CI/CD Workflows"]:::external
    CI -->|"runs tests"| E2E
    CI -->|"build & publish"| DockerBuild

    subgraph "Docker Build Definitions"
        DCLI["docker/Dockerfile.cli"]:::infra
        DDaemon["docker/Dockerfile.daemon"]:::infra
        DLocal["docker/Dockerfile.local"]:::infra
        DSwag["docker/Dockerfile.swag"]:::infra
    end
    CI -->|"use definitions"| DCLI
    CI -->|"use definitions"| DDaemon
    CI -->|"use definitions"| DLocal
    CI -->|"use definitions"| DSwag

    %% Click Events
    click CLI "https://github.com/stamusnetworks/stamusctl/tree/main/cmd/ctl"
    click HTTP "https://github.com/stamusnetworks/stamusctl/tree/main/cmd/daemon"
    click Main "https://github.com/stamusnetworks/stamusctl/blob/main/cmd/main.go"
    click ComposeCmd "https://github.com/stamusnetworks/stamusctl/tree/main/cmd/ctl/compose"
    click ConfigCmd "https://github.com/stamusnetworks/stamusctl/tree/main/cmd/ctl/config"
    click TemplateCmd "https://github.com/stamusnetworks/stamusctl/tree/main/cmd/ctl/template"
    click LoginCmd "https://github.com/stamusnetworks/stamusctl/blob/main/cmd/ctl/login.go"
    click VersionCmd "https://github.com/stamusnetworks/stamusctl/blob/main/cmd/ctl/version.go"
    click HTTP "https://github.com/stamusnetworks/stamusctl/tree/main/cmd/daemon"
    click Handlers "https://github.com/stamusnetworks/stamusctl/tree/main/internal/handlers"
    click Models "https://github.com/stamusnetworks/stamusctl/tree/main/internal/models"
    click ComposeSvc "https://github.com/stamusnetworks/stamusctl/tree/main/internal/docker-compose"
    click DockerSvc "https://github.com/stamusnetworks/stamusctl/tree/main/internal/docker"
    click Embeds "https://github.com/stamusnetworks/stamusctl/tree/main/internal/embeds"
    click Auth "https://github.com/stamusnetworks/stamusctl/tree/main/internal/auth"
    click Logging "https://github.com/stamusnetworks/stamusctl/tree/main/internal/logging"
    click Utils "https://github.com/stamusnetworks/stamusctl/tree/main/internal/utils"
    click App "https://github.com/stamusnetworks/stamusctl/tree/main/internal/app"
    click E2E "https://github.com/stamusnetworks/stamusctl/blob/main/.test"
    click CI "https://github.com/stamusnetworks/stamusctl/tree/main/.github/workflows"
    click DCLI "https://github.com/stamusnetworks/stamusctl/blob/main/docker/Dockerfile.cli"
    click DDaemon "https://github.com/stamusnetworks/stamusctl/blob/main/docker/Dockerfile.daemon"
    click DLocal "https://github.com/stamusnetworks/stamusctl/blob/main/docker/Dockerfile.local"
    click DSwag "https://github.com/stamusnetworks/stamusctl/blob/main/docker/Dockerfile.swag"

    %% Styles
    classDef cli fill:#f9f,stroke:#333,stroke-width:1px
    classDef api fill:#9ff,stroke:#333,stroke-width:1px
    classDef logic fill:#9f9,stroke:#333,stroke-width:1px
    classDef infra fill:#99f,stroke:#333,stroke-width:1px
    classDef tpl fill:#ff9,stroke:#333,stroke-width:1px
    classDef external fill:#f99,stroke:#333,stroke-width:1px
```
