# gadget-inc/ggt architecture

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

- Interactive diagram: https://gitdiagram.com/gadget-inc/ggt
- Repository: https://github.com/gadget-inc/ggt

## Overview

##### Main Components

- CLI Entry Point & Command Dispatcher:
– Main files are in the “src” directory (e.g. src/main.ts and src/ggt.ts) which bootstrap the CLI.
– The “src/commands” folder holds individual command implementations. Each command (e.g. dev, deploy, etc.) represents an interaction point with the Gadget cloud.

- Core Services and Modules:
– The “src/services” directory is broken down into multiple subfolders such as “app”, “command”, “config”, “filesync”, “http”, “output”, “user”, and “util”. These represent the core functionality:
- App Service: Handles application-level operations (e.g., synchronizing the app files, handling client/server interactions).
- Filesync Service: Manages file changes, conflict detection/resolution, and directory updates.
- Command Service: Processes arguments and maps the CLI commands to the underlying operations.
- Config Service: Reads environment configurations, local state (like .gadget/sync.json), and manages metadata.
- HTTP Service: Interfaces with Gadget’s remote cloud API for authentication, syncing, deploying, and retrieving data.
- Output/Logging Service: Formatting logs, pretty printing, and handling user prompts/feedback.
- Util Services: Helpers for JSON processing, file paths, and promise handling.

- External Connectivity:
– The CLI communicates with Gadget’s cloud environment (an external system) via HTTP calls and possibly GraphQL (as implied by “graphql-codegen.yml” and generated files in “src/__generated__”).
– Additional external integrations include dependency on npm, GitHub workflows (for CI/CD), and possibly telemetry/logging endpoints.

##### Relationships & Interactions

- The CLI Entry Point accepts user commands and dispatches them to the relevant command implementation.
- Each command (e.g., “ggt dev”, “ggt deploy”) calls into one or more underlying services:
– For instance, a “dev” command will trigger the Filesync service to synchronize file changes with the cloud, run the HTTP service to connect to Gadget’s backend, and use the Config service to determine parameters.
– The Filesync service interacts with local folders (monitoring for changes) and deals with conflict resolution as described.
- The HTTP service is responsible for making requests to the Gadget API endpoints.
- Logging and user output are handled by dedicated services (located in “src/services/output”), ensuring clear user feedback.
- The command layer and services depend on utilities in “src/services/util” for common tasks like JSON handling, assertion, and path management.

##### Architectural Patterns & Design Principles

- Modular Design: Components are divided into distinct directories (commands, various services, utilities). This separation supports a clean, maintainable, and testable codebase.
- Extensibility: The “ggt add” command shows that users can extend their applications (models, fields, actions, and routes) easily, implying a design that is built for plugin-like additions.
- CLI Best Practices: With clear separation between CLI argument parsing, command execution, and the business logic in services.
- Sync/Conflict Resolution: The use of a .ignore file, file watchers, and sync JSON file indicate robust local-to-cloud synchronization logic.

##### Relevant Technologies, Frameworks, and Libraries

- Node.js/TypeScript: Evidenced by the .ts files throughout “src” and “spec”.
- GraphQL: There is code generation seen in “graphql-codegen.yml” and generated GraphQL modules in “src/__generated__”.
- Testing: Extensive testing is structured in the “spec” folder, which may use tools like Vitest (supported by “vitest.config.js”).
- Code formatting and linting tools are evident (.prettierrc.json, .eslintrc.json, cspell configuration).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "CLI Core"
        CLI1("CLI Entry: main.ts"):::cli
        CLI2("CLI Entry: ggt.ts"):::cli
    end

    subgraph "Command Modules"
        CMD("Commands"):::command
    end

    subgraph "Core Services"
        S1("App Service"):::service
        S2("Filesync Service"):::service
        S3("Command Service"):::service
        S4("Config Service"):::service
        S5("HTTP Service"):::service
        S6("Output/Logging Service"):::service
        S7("Util Service"):::service
        S8("GraphQL Integration"):::service
    end

    subgraph "External Systems"
        EX1("Gadget Cloud API"):::external
        EX2("Local File System"):::external
    end

    %% Connections from CLI Core to Command Modules
    CLI1 -->|"dispatch"| CMD
    CLI2 -->|"dispatch"| CMD

    %% Command Modules trigger the Command Service and GraphQL Integration
    CMD -->|"invokes"| S3
    CMD -->|"uses"| S8

    %% Command Service routes commands to core services
    S3 -->|"triggers"| S1
    S3 -->|"triggers"| S2
    S3 -->|"triggers"| S4
    S3 -->|"triggers"| S5
    S3 -->|"triggers"| S6
    S3 -->|"triggers"| S7

    %% External interactions
    S1 -->|"syncs with"| EX1
    S1 -->|"reads/writes"| EX2

    S2 -->|"monitors"| EX2
    S2 -->|"synchronizes to"| EX1

    S4 -->|"loads from"| EX2

    S5 -->|"calls"| EX1

    S8 -->|"queries"| EX1

    %% Styles
    classDef cli fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef command fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef service fill:#f9844a,stroke:#000,stroke-width:2px;
    classDef external fill:#277da1,stroke:#000,stroke-width:2px;

    %% Click Events
    click CLI1 "https://github.com/gadget-inc/ggt/blob/main/src/main.ts"
    click CLI2 "https://github.com/gadget-inc/ggt/blob/main/src/ggt.ts"
    click CMD "https://github.com/gadget-inc/ggt/tree/main/src/commands"
    click S1 "https://github.com/gadget-inc/ggt/tree/main/src/services/app"
    click S2 "https://github.com/gadget-inc/ggt/tree/main/src/services/filesync"
    click S3 "https://github.com/gadget-inc/ggt/tree/main/src/services/command"
    click S4 "https://github.com/gadget-inc/ggt/tree/main/src/services/config"
    click S5 "https://github.com/gadget-inc/ggt/tree/main/src/services/http"
    click S6 "https://github.com/gadget-inc/ggt/tree/main/src/services/output"
    click S7 "https://github.com/gadget-inc/ggt/tree/main/src/services/util"
    click S8 "https://github.com/gadget-inc/ggt/tree/main/src/__generated__"
```
