# checkmarx/ast-cli architecture

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

- Interactive diagram: https://gitdiagram.com/checkmarx/ast-cli
- Repository: https://github.com/checkmarx/ast-cli

## Overview

##### Project Type and Purpose
- Project Type: A standalone, cross‐platform CLI tool written in Go.
- Purpose: Exposes Checkmarx One platform functionality (scans, results, policies, user counts, chat integrations, etc.) via a local binary.
- Key Indicators:
– `cmd/main.go` entrypoint
– `internal/commands/*` packages implementing CLI commands
– `internal/services/*` orchestration of business logic
– `internal/wrappers/*` HTTP & gRPC clients to remote APIs

##### File Structure
Top‐level layout:
- cmd – entrypoint & root command
- internal/commands – individual CLI subcommands (scan, auth, project, chat, asca, sca‐realtime, etc.)
- internal/services – core business logic (projects, policies, export)
- internal/wrappers – low‐level API clients (REST, gRPC, mocks for testing)
- internal/params, constants, logger – configuration, flags, environment, logging
- test directories – unit & integration suites

Architectural Pattern:
Layered architecture:
CLI layer → Command layer → Service layer → Wrapper (API) layer → External Checkmarx One platform

##### README Insights
- Confirms it’s a CLI executable (“Checkmarx CLI is a standalone Checkmarx tool”)
- Lists Go as the language and shows build targets for multiple OS/architectures

##### Main Components & Relationships
a. Components:
1. CLI Entrypoint (cmd)
2. Command Processor (internal/commands)
3. Business Service Layer (internal/services)
4. API Wrapper Layer (internal/wrappers)
5. Core Utilities & Config (internal/logger, internal/params, internal/constants)
6. External Checkmarx One Platform (REST & gRPC endpoints)
7. Test Harness & Mocks (internal/wrappers/mock, test/integration)

b. Relationships / Data Flows:
- User types command → CLI Entrypoint
- Entrypoint routes to specific Command module
- Command invokes Service(s), passing parsed flags & configuration
- Service calls Wrapper client (HTTP or gRPC) to perform remote operations
- Wrapper returns raw payload → Service transforms → Command prints via Printer util
- All layers use shared Config & Logging components

c. Architectural Patterns & Principles:
- Layered Separation of Concerns (each layer has a single responsibility)
- Dependency Injection via Go interfaces (commands depend on service interfaces, services depend on wrapper interfaces)
- Mockable API clients (wrappers/mock) to facilitate testing
- Platform‐agnostic CLI core with OS‐specific build targets

d. Key Technologies:
- Go modules & packages
- Cobra (or similar) for CLI parsing (inferred from command structure)
- HTTP REST clients (net/http wrappers)
- gRPC clients (internal/wrappers/grpcs)
- Makefile & Dockerfile for builds & CI
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers
    subgraph "CLI Layer"
        CLI["CLI Entrypoint"]:::cli
    end
    subgraph "Command Layer"
        Cmd["Command Processor\n(internal/commands)"]:::commands
    end
    subgraph "Service Layer"
        Svc["Business Service Layer\n(internal/services)"]:::services
    end
    subgraph "Wrapper Layer"
        Wrap["API Wrapper Layer\n(internal/wrappers)"]:::wrappers
    end
    subgraph "External Platform"
        Ext["External Checkmarx One Platform"]:::external
    end
    subgraph "Shared Utilities"
        Config["Config & Flags\n(internal/params)"]:::shared
        Logger["Logger\n(internal/logger)"]:::shared
        Const["Constants\n(internal/constants)"]:::shared
    end
    subgraph "Test Harness & Mocks"
        Mock["Wrapper Mocks\n(internal/wrappers/mock)"]:::tests
        Integration["Integration Tests\ntest/integration"]:::tests
    end

    %% Data Flows
    CLI -->|"invoke command"| Cmd
    Cmd -->|"calls services"| Svc
    Svc -->|"REST/gRPC"| Wrap
    Wrap -->|"HTTP JSON/Protobuf"| Ext

    %% Shared Utilities Dependencies
    Config -.-> CLI
    Config -.-> Cmd
    Config -.-> Svc
    Config -.-> Wrap

    Logger -.-> CLI
    Logger -.-> Cmd
    Logger -.-> Svc
    Logger -.-> Wrap

    Const -.-> CLI
    Const -.-> Cmd
    Const -.-> Svc
    Const -.-> Wrap

    %% Test Harness Connections
    Mock --> Wrap
    Integration --> CLI

    %% Click Events
    click CLI "https://github.com/checkmarx/ast-cli/blob/main/cmd/main.go"
    click Cmd "https://github.com/checkmarx/ast-cli/tree/main/internal/commands"
    click Svc "https://github.com/checkmarx/ast-cli/tree/main/internal/services"
    click Wrap "https://github.com/checkmarx/ast-cli/tree/main/internal/wrappers"
    click Config "https://github.com/checkmarx/ast-cli/tree/main/internal/params"
    click Logger "https://github.com/checkmarx/ast-cli/tree/main/internal/logger"
    click Const "https://github.com/checkmarx/ast-cli/tree/main/internal/constants"
    click Mock "https://github.com/checkmarx/ast-cli/tree/main/internal/wrappers/mock"
    click Integration "https://github.com/checkmarx/ast-cli/tree/main/test/integration"

    %% Styles
    classDef cli fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef commands fill:#d4edda,stroke:#333,stroke-width:1px
    classDef services fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef wrappers fill:#d6d8fb,stroke:#333,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef shared fill:#bee5eb,stroke:#333,stroke-width:1px
    classDef tests fill:#f8d7da,stroke:#333,stroke-width:1px

    class CLI cli
    class Cmd commands
    class Svc services
    class Wrap wrappers
    class Ext external
    class Config shared
    class Logger shared
    class Const shared
    class Mock tests
    class Integration tests
```
