# chronicle/cli architecture

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

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

## Overview

##### Project type and purpose
- This is a Python-based command-line interface (CLI) tool.
- Purpose: allow users to manage Chronicle Security Operations resources (Feeds, Parsers, Forwarders, BigQuery access, etc.) by calling Google Chronicle REST APIs.

##### Main components
- CLI Entry Point (main.py / console script “chronicle_cli”)
- Command Dispatcher / Parser (handles subcommands)
- Domain Modules:
- Feeds
- Parsers
- Forwarders
- Tools (BigQuery, access)
- Common Utilities:
- Authentication (chronicle_auth)
- API Utility (HTTP request builder, retry, error handling)
- Command-line option parsing / templates / constants
- External Services:
- Chronicle Security Operations REST APIs
- (BigQuery API for tools module)
- Local Credentials Store (.chronicle_cli/chronicle_credentials.json)

##### Relationships and data flow
1. User runs “chronicle_cli <domain> <action> [flags]”.
2. Entry point (main.py) invokes the command dispatcher.
3. Dispatcher loads the appropriate domain module (e.g., feeds/commands/create.py).
4. Domain command calls into Common Utilities:
– chronicle_auth to fetch/refresh OAuth token from credentials file
– api_utility to build and send HTTP request
– file_utility or templates for payload or output formatting
5. HTTP client hits Google Chronicle REST endpoint.
6. Response is returned through api_utility back to the command, which formats output to console.

##### Key architectural patterns / principles
- Modularization by domain (Feeds, Parsers, Forwarders, Tools)
- DRY common library for authentication, HTTP, constants, and templating
- Single process CLI with sub-command dispatch (flat structure, not microservices)
- Clear separation of concerns:
- Domain logic in each “<domain>/commands”
- Shared HTTP and auth in “common”
- Tests co-located alongside modules

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User"]:::external
    CLI["CLI Entry Point\n(main.py)"]:::cli
    CommandDispatcher["Command Dispatcher\n(common/commands_utility.py)"]:::common
    OptionsParser["Options Parser\n(common/options.py)"]:::common

    subgraph "Domain Modules"
        Feeds["Feeds Module\nfeeds/commands/ & feeds.py"]:::domain
        Parsers["Parsers Module\nparsers/commands/ & parsers.py"]:::domain
        Forwarders["Forwarders Module\nforwarders/commands/ & forwarders.py"]:::domain
        Tools["Tools Module\ntools/commands/ & bigquery.py"]:::domain
    end

    subgraph "Common Utilities"
        Auth["Auth Module\ncommon/chronicle_auth.py"]:::common
        APIUtil["API Utility\ncommon/api_utility.py"]:::common
        FileUtil["File Utility\ncommon/file_utility.py"]:::common
        Templates["Templates Engine\ncommon/templates.py"]:::common
        Constants["Shared Constants\ncommon/constants/"]:::common
    end

    subgraph "External Services"
        ChronicleAPI["Chronicle REST APIs"]:::external
        BigQueryAPI["BigQuery API"]:::external
    end

    Credentials["Credentials Store\n(.chronicle_cli/chronicle_credentials.json)"]:::credentials

    User --> CLI
    CLI --> CommandDispatcher
    CommandDispatcher --> OptionsParser
    CommandDispatcher --> Feeds
    CommandDispatcher --> Parsers
    CommandDispatcher --> Forwarders
    CommandDispatcher --> Tools

    Feeds --> Auth
    Parsers --> Auth
    Forwarders --> Auth
    Tools --> Auth

    Feeds --> APIUtil
    Parsers --> APIUtil
    Forwarders --> APIUtil
    Tools --> APIUtil

    Auth --> Credentials
    APIUtil --> ChronicleAPI
    ChronicleAPI --> APIUtil

    Tools --> BigQueryAPI

    click CLI "https://github.com/chronicle/cli/blob/main/main.py"
    click CommandDispatcher "https://github.com/chronicle/cli/blob/main/common/commands_utility.py"
    click OptionsParser "https://github.com/chronicle/cli/blob/main/common/options.py"
    click Auth "https://github.com/chronicle/cli/blob/main/common/chronicle_auth.py"
    click APIUtil "https://github.com/chronicle/cli/blob/main/common/api_utility.py"
    click FileUtil "https://github.com/chronicle/cli/blob/main/common/file_utility.py"
    click Templates "https://github.com/chronicle/cli/blob/main/common/templates.py"
    click Constants "https://github.com/chronicle/cli/tree/main/common/constants/"
    click Feeds "https://github.com/chronicle/cli/tree/main/feeds/commands/"
    click Parsers "https://github.com/chronicle/cli/tree/main/parsers/commands/"
    click Forwarders "https://github.com/chronicle/cli/tree/main/forwarders/commands/"
    click Tools "https://github.com/chronicle/cli/blob/main/tools/bigquery.py"

    classDef cli fill:#ffe4b5,stroke:#333,stroke-width:1px
    classDef domain fill:#add8e6,stroke:#333,stroke-width:1px
    classDef common fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#f4c2c2,stroke:#333,stroke-width:1px
    classDef credentials fill:#ffdab9,stroke:#333,stroke-width:1px
```
