# mbrt/gmailctl architecture

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

- Interactive diagram: https://gitdiagram.com/mbrt/gmailctl
- Repository: https://github.com/mbrt/gmailctl

## Overview

##### Project type and purpose
- gmailctl is a Go‑based command‑line utility (CLI tool) for managing Gmail filters declaratively.
- It defines two executables in cmd/:
- gmailctl – the main CLI (commands: init, edit, diff, apply, download, export, test)
- gmailctl‑config‑migrate – a subtool to convert older YAML filters to the current Jsonnet format
- Core functionality: read a Jsonnet config, build an in‑memory representation of filters+actions, diff vs. remote Gmail settings, and apply changes via Gmail’s REST API.

##### High‑level file‑structure analysis
- /cmd: entry points; one for the main CLI, one for the migration tool. They parse flags, load config, dispatch to subcommands.
- /internal: core packages, each encapsulating a layer of the pipeline:
- data: default config, static assets (JSONNET libs)
- engine: subpackages implementing all phases
– config: read & validate Jsonnet config (v1alpha1, v1alpha2, v1alpha3 support)
– parser: Jsonnet → AST → internal filters model
– filter & label & gmail & apply & export: build Gmail API calls or XML exports; compute diffs
– cfgtest: run “test” subcommand against synthetic messages
– api: wrap Gmail REST endpoints ( filters, labels )
– rimport: re‑import downloaded XML/JSON into Jsonnet
- localcred: OAuth2 flow / local HTTP server for user consent
- fakegmail: a fake Gmail server for testing
- graph: auxiliary matching algorithms (e.g., for diffing lists)
- reporting, stringset, errors: utility libraries
- Snapcraft, GitHub workflows, integration_test.go – CI, packaging, and E2E tests.

##### Key architecture insights from README
- Separation of concerns: config reading → rule/model construction → diff/export → apply
- Use of Jsonnet for configuration → requires a parser phase
- Two modes of output: Gmail REST calls (apply) and XML filter export (export)
- Test harness (cfgtest) isolates model from real Gmail API

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI_Main["gmailctl"]:::cli
        CLI_Migrate["gmailctl-config-migrate"]:::cli
    end

    %% Configuration & Static Data
    subgraph "Configuration" 
        direction TB
        ConfigFiles["Jsonnet/YAML Files"]:::config
        StaticData["Static Data (internal/data)"]:::config
    end

    %% Config Loader & Versions
    subgraph "Config Loader & Versions"
        direction TB
        ConfigLoader["Config Loader (read.go)"]:::config
        ConfigV1["v1alpha3 Definitions"]:::config
    end

    %% Parser
    subgraph "Parser"
        direction TB
        ParserNode["Parser (parser.go)"]:::config
        ASTNode["AST (ast.go)"]:::config
    end

    %% Core Engine Pipeline
    subgraph "Core Engine" 
        direction TB
        subgraph "Model Builder"
            direction TB
            FilterMod["Filter Module"]:::engine
            LabelMod["Label Module"]:::engine
            GmailStruct["Gmail Structures"]:::engine
        end
        subgraph "Diff & Export"
            direction TB
            APIExport["API Export"]:::engine
            XMLExport["XML Export"]:::engine
        end
        ApplyMod["Apply Module"]:::engine
        TestHarness["Test Harness"]:::test
    end

    %% API Client & Auth
    subgraph "Gmail API Client & Auth"
        direction TB
        GmailClient["Gmail API Client"]:::engine
        OAuth2["OAuth2 Provider"]:::engine
    end

    %% External & Test Servers
    subgraph "External Services & Test"
        direction TB
        GmailAPI["Gmail REST API"]:::external
        FakeGmail["Fake Gmail Server"]:::test
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        GraphAlg["Matching Algorithms"]:::test
        ErrUtil["Errors"]:::util
        ReportUtil["Reporting"]:::util
        StrsetUtil["String Sets"]:::util
    end

    %% Relationships
    CLI_Main -->|"init/edit/diff/apply/download/export/test"| ConfigLoader
    CLI_Migrate -->|"migrate YAML → Jsonnet"| ConfigLoader
    ConfigFiles --> ConfigLoader
    StaticData --> ConfigLoader
    ConfigLoader --> ConfigV1
    ConfigLoader --> ParserNode
    ParserNode --> ASTNode
    ASTNode --> FilterMod
    ASTNode --> LabelMod
    ASTNode --> GmailStruct
    FilterMod --> APIExport
    LabelMod --> APIExport
    APIExport --> ApplyMod
    XMLExport --> CLI_Main
    FilterMod --> XMLExport
    LabelMod --> XMLExport
    ApplyMod --> OAuth2
    OAuth2 --> GmailAPI
    ApplyMod --> GmailClient
    GmailClient --> GmailAPI
    TestHarness --> ASTNode
    TestHarness --> FakeGmail
    FakeGmail --> GmailClient
    GraphAlg --> FilterMod
    GraphAlg --> LabelMod
    ErrUtil --> CLI_Main
    ErrUtil --> ApplyMod
    ReportUtil --> CLI_Main
    StrsetUtil --> FilterMod

    %% Click Events
    click CLI_Main "https://github.com/mbrt/gmailctl/tree/master/cmd/gmailctl"
    click CLI_Migrate "https://github.com/mbrt/gmailctl/tree/master/cmd/gmailctl-config-migrate"
    click StaticData "https://github.com/mbrt/gmailctl/tree/master/internal/data"
    click ConfigLoader "https://github.com/mbrt/gmailctl/blob/master/internal/engine/config/read.go"
    click ConfigV1 "https://github.com/mbrt/gmailctl/blob/master/internal/engine/config/v1alpha3/config.go"
    click ParserNode "https://github.com/mbrt/gmailctl/blob/master/internal/engine/parser/parser.go"
    click ASTNode "https://github.com/mbrt/gmailctl/blob/master/internal/engine/parser/ast.go"
    click FilterMod "https://github.com/mbrt/gmailctl/tree/master/internal/engine/filter"
    click LabelMod "https://github.com/mbrt/gmailctl/tree/master/internal/engine/label"
    click GmailStruct "https://github.com/mbrt/gmailctl/blob/master/internal/engine/gmail/consts.go"
    click APIExport "https://github.com/mbrt/gmailctl/blob/master/internal/engine/export/api/api_export.go"
    click XMLExport "https://github.com/mbrt/gmailctl/blob/master/internal/engine/export/xml/consts.go"
    click ApplyMod "https://github.com/mbrt/gmailctl/blob/master/internal/engine/apply/apply.go"
    click TestHarness "https://github.com/mbrt/gmailctl/blob/master/internal/engine/cfgtest/cfgtest.go"
    click GmailClient "https://github.com/mbrt/gmailctl/blob/master/internal/engine/api/api.go"
    click OAuth2 "https://github.com/mbrt/gmailctl/blob/master/cmd/gmailctl/localcred/oauth2_server.go"
    click FakeGmail "https://github.com/mbrt/gmailctl/blob/master/internal/fakegmail/fakegmail.go"
    click GraphAlg "https://github.com/mbrt/gmailctl/blob/master/internal/graph/munkres.go"
    click ErrUtil "https://github.com/mbrt/gmailctl/blob/master/internal/errors/err.go"
    click ReportUtil "https://github.com/mbrt/gmailctl/blob/master/internal/reporting/pretty.go"
    click StrsetUtil "https://github.com/mbrt/gmailctl/blob/master/internal/stringset/stringset.go"

    %% Classes
    classDef cli fill:#bbdefb,stroke:#333,stroke-width:1px;
    classDef config fill:#c8e6c9,stroke:#333,stroke-width:1px;
    classDef engine fill:#ffe0b2,stroke:#333,stroke-width:1px;
    classDef external fill:#eceff1,stroke:#333,stroke-width:1px;
    classDef test fill:#fff9c4,stroke:#333,stroke-width:1px;
    classDef util fill:#e1bee7,stroke:#333,stroke-width:1px;
```
