# gam-team/gam architecture

> Architecture diagram of the GitHub repository gam-team/gam, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gam-team/gam
- Repository: https://github.com/gam-team/gam

## Overview

#### Purpose and Runtime
GAM is a Python command-line administration client for Google Workspace domains and users. It runs locally on administrator machines, is installable as `gam7`, and is also packaged for Windows/Linux/macOS distribution. Its operational boundary is the local CLI versus authenticated Google APIs.

Paths: `pyproject.toml`, `src/gam/__main__.py`, `src/gam.py`

#### Entry Points and Command Dispatch
The executable/module entry point initializes GAM and routes command-line invocations into the main command implementation. The large command surface is centralized in `gam.py`; legacy launch/setup wrappers support installed distributions.

Paths: `src/gam/__main__.py`, `src/gam.py`, `src/callgam.py`

#### CLI Parsing and Execution Model
Commands are parsed into actions, entities, and API operations. The `gamlib` layer separates argument parsing, action dispatch, entity expansion, global state/configuration, output messages, and API-facing operations. This is the principal control-flow backbone: CLI arguments → parsed action/entity → selected Google API calls → formatted output/exit status.

Paths: `src/gam/gamlib/glclargs.py`, `src/gam/gamlib/glaction.py`, `src/gam/gamlib/glentity.py`

#### Google API Integration
GAM manages Workspace resources through Google APIs, with shared API construction and request orchestration in the GAM library. Bundled discovery documents extend supported services—including CBCM, Meet, Looker Studio, Contact Delegation, and Service Account Lookup—without requiring those schemas to be fetched at runtime.

Paths: `src/gam/gamlib/glapi.py`, `src/gam/gamlib/glgapi.py`, `src/gam/cbcm-v1.1beta1.json`

#### Authentication and HTTP Boundary
Authentication, token storage, HTTP transport, URL handling, and service-client abstractions are implemented in the embedded `atom` package. This is the security and network boundary between local credentials/configuration and Google endpoints; it includes mock transport/service implementations for non-networked behavior.

Paths: `src/gam/atom/auth.py`, `src/gam/atom/token_store.py`, `src/gam/atom/http.py`

#### Legacy Google Data APIs
Alongside modern Google API integration, GAM carries a vendored `gdata` implementation for older Google Data APIs and specialized services such as audit and contacts. This preserves compatibility for command areas not represented solely by newer REST clients.

Paths: `src/gam/gdata/service.py`, `src/gam/gdata/apps/audit/service.py`, `src/gam/gdata/apps/contacts/service.py`

#### Distribution, Trust, and Automation
Packaging supports Python distribution plus native installers/bundles: PyInstaller spec, Windows Inno Setup, and WiX. A bundled CA bundle supports TLS validation. GitHub Actions builds releases, publishes PyPI artifacts, refreshes CA certificates, and maintains wiki/dependencies.

Paths: `src/gam.spec`, `src/gam.iss`, `.github/workflows/build.yml`

Main entry points: [`src/gam/gdata/service.py`](https://github.com/gam-team/gam/blob/main/src/gam/gdata/service.py) (Legacy GData services), [`src/gam/gamlib/glclargs.py`](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glclargs.py) (Argument parsing), [`src/gam/gamlib/glaction.py`](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glaction.py) (Action dispatch), [`src/gam/gamlib/glgapi.py`](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glgapi.py) (Google API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["Local CLI"]
  node_entry["Module entry point<br/>CLI bootstrap<br/>[__main__.py]"]
  node_command_core["Command implementation<br/>command dispatcher<br/>[gam.py]"]
  node_legacy_launcher["Legacy launcher<br/>launch wrapper<br/>[callgam.py]"]
  node_arguments["Argument parsing<br/>parser<br/>[glclargs.py]"]
  node_actions["Action dispatch<br/>dispatcher<br/>[glaction.py]"]
  node_entities["Entity expansion<br/>resolver<br/>[glentity.py]"]
end

subgraph group_api["API Integration"]
  node_api_layer["API orchestration<br/>GAM API layer<br/>[glapi.py]"]
  node_gapi_client["Google API client<br/>service client layer<br/>[glgapi.py]"]
  node_discovery["Bundled discovery docs<br/>API schemas"]
  node_auth["Authentication<br/>credential auth<br/>[auth.py]"]
  node_token_store[("Token storage<br/>credential store<br/>[token_store.py]")]
  node_http["HTTP transport<br/>network boundary<br/>[http.py]"]
  node_gdata["Legacy GData services<br/>vendored API client<br/>[service.py]"]
  node_audit_service["Audit service<br/>legacy specialized service<br/>[service.py]"]
  node_contacts_service["Contacts service<br/>legacy specialized service<br/>[service.py]"]
end

subgraph group_distribution["Distribution &amp; Automation"]
  node_project["Python package<br/>packaging metadata<br/>[pyproject.toml]"]
  node_native_packaging["Native bundles<br/>installer definitions<br/>[gam.spec]"]
  node_release_workflow["Release workflow<br/>GitHub Actions<br/>[build.yml]"]
end

node_google_apis{{"Google Workspace APIs<br/>external APIs"}}

node_project -->|"installs"| node_entry
node_entry -->|"invokes"| node_command_core
node_legacy_launcher -->|"launches"| node_command_core
node_command_core -->|"parses CLI"| node_arguments
node_arguments -->|"selects action"| node_actions
node_arguments -->|"selects entities"| node_entities
node_actions -->|"executes operations"| node_api_layer
node_entities -->|"supplies targets"| node_api_layer
node_api_layer -->|"orchestrates"| node_gapi_client
node_gapi_client -->|"uses schemas"| node_discovery
node_gapi_client -->|"authenticates through"| node_auth
node_auth -->|"reads and stores tokens"| node_token_store
node_auth -->|"authorizes transport"| node_http
node_http -->|"HTTPS requests"| node_google_apis
node_actions -.->|"uses legacy commands"| node_gdata
node_gdata -->|"provides"| node_audit_service
node_gdata -->|"provides"| node_contacts_service
node_gdata -.->|"legacy API requests"| node_google_apis
node_native_packaging -->|"packages"| node_project
node_release_workflow -->|"builds"| node_native_packaging
node_release_workflow -->|"publishes"| node_project

click node_project "https://github.com/gam-team/gam/blob/main/pyproject.toml"
click node_entry "https://github.com/gam-team/gam/blob/main/src/gam/__main__.py"
click node_command_core "https://github.com/gam-team/gam/blob/main/src/gam.py"
click node_legacy_launcher "https://github.com/gam-team/gam/blob/main/src/callgam.py"
click node_arguments "https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glclargs.py"
click node_actions "https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glaction.py"
click node_entities "https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glentity.py"
click node_api_layer "https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glapi.py"
click node_gapi_client "https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glgapi.py"
click node_discovery "https://github.com/gam-team/gam/blob/main/src/gam/cbcm-v1.1beta1.json"
click node_auth "https://github.com/gam-team/gam/blob/main/src/gam/atom/auth.py"
click node_token_store "https://github.com/gam-team/gam/blob/main/src/gam/atom/token_store.py"
click node_http "https://github.com/gam-team/gam/blob/main/src/gam/atom/http.py"
click node_gdata "https://github.com/gam-team/gam/blob/main/src/gam/gdata/service.py"
click node_audit_service "https://github.com/gam-team/gam/blob/main/src/gam/gdata/apps/audit/service.py"
click node_contacts_service "https://github.com/gam-team/gam/blob/main/src/gam/gdata/apps/contacts/service.py"
click node_native_packaging "https://github.com/gam-team/gam/blob/main/src/gam.spec"
click node_release_workflow "https://github.com/gam-team/gam/blob/main/.github/workflows/build.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_command_core,node_legacy_launcher,node_arguments,node_actions,node_entities toneBlue
class node_api_layer,node_gapi_client,node_discovery,node_auth,node_token_store,node_http,node_gdata,node_audit_service,node_contacts_service toneAmber
class node_project,node_native_packaging,node_release_workflow toneMint
class node_google_apis toneNeutral
```

## Components

### Local CLI

Command parsing and execution on administrator machines.

- [Module entry point](https://github.com/gam-team/gam/blob/main/src/gam/__main__.py): CLI bootstrap · `src/gam/__main__.py`
- [Command implementation](https://github.com/gam-team/gam/blob/main/src/gam.py): command dispatcher · Centralized GAM command surface. · `src/gam.py`
- [Legacy launcher](https://github.com/gam-team/gam/blob/main/src/callgam.py): launch wrapper · `src/callgam.py`
- [Argument parsing](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glclargs.py): parser · `src/gam/gamlib/glclargs.py`
- [Action dispatch](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glaction.py): dispatcher · `src/gam/gamlib/glaction.py`
- [Entity expansion](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glentity.py): resolver · `src/gam/gamlib/glentity.py`

### API Integration

Google Workspace API clients and compatibility layers.

- [API orchestration](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glapi.py): GAM API layer · Builds services and executes Google API requests. · `src/gam/gamlib/glapi.py`
- [Google API client](https://github.com/gam-team/gam/blob/main/src/gam/gamlib/glgapi.py): service client layer · `src/gam/gamlib/glgapi.py`
- [Bundled discovery docs](https://github.com/gam-team/gam/blob/main/src/gam/cbcm-v1.1beta1.json): API schemas · Adds supported services without runtime schema fetches. · `src/gam/cbcm-v1.1beta1.json`
- [Authentication](https://github.com/gam-team/gam/blob/main/src/gam/atom/auth.py): credential auth · `src/gam/atom/auth.py`
- [Token storage](https://github.com/gam-team/gam/blob/main/src/gam/atom/token_store.py): credential store · `src/gam/atom/token_store.py`
- [HTTP transport](https://github.com/gam-team/gam/blob/main/src/gam/atom/http.py): network boundary · Transports authenticated requests to Google endpoints. · `src/gam/atom/http.py`
- [Legacy GData services](https://github.com/gam-team/gam/blob/main/src/gam/gdata/service.py): vendored API client · Compatibility client for older Google Data API command areas. · `src/gam/gdata/service.py`
- [Audit service](https://github.com/gam-team/gam/blob/main/src/gam/gdata/apps/audit/service.py): legacy specialized service · `src/gam/gdata/apps/audit/service.py`
- [Contacts service](https://github.com/gam-team/gam/blob/main/src/gam/gdata/apps/contacts/service.py): legacy specialized service · `src/gam/gdata/apps/contacts/service.py`

### Distribution & Automation

Packaging, installers, trust material, and release workflows.

- [Python package](https://github.com/gam-team/gam/blob/main/pyproject.toml): packaging metadata · `pyproject.toml`
- [Native bundles](https://github.com/gam-team/gam/blob/main/src/gam.spec): installer definitions · PyInstaller and Windows installer packaging. · `src/gam.spec`
- [Release workflow](https://github.com/gam-team/gam/blob/main/.github/workflows/build.yml): GitHub Actions · Builds releases, publishes artifacts, and maintains dependencies. · `.github/workflows/build.yml`

### Other components

- **Google Workspace APIs**: external APIs

## Connections

- Python package → Module entry point: installs
- Module entry point → Command implementation: invokes
- Legacy launcher → Command implementation: launches
- Command implementation → Argument parsing: parses CLI
- Argument parsing → Action dispatch: selects action
- Argument parsing → Entity expansion: selects entities
- Action dispatch → API orchestration: executes operations
- Entity expansion → API orchestration: supplies targets
- API orchestration → Google API client: orchestrates
- Google API client → Bundled discovery docs: uses schemas
- Google API client → Authentication: authenticates through
- Authentication → Token storage: reads and stores tokens
- Authentication → HTTP transport: authorizes transport
- HTTP transport → Google Workspace APIs: HTTPS requests
- Action dispatch → Legacy GData services: uses legacy commands
- Legacy GData services → Audit service: provides
- Legacy GData services → Contacts service: provides
- Legacy GData services → Google Workspace APIs: legacy API requests
- Native bundles → Python package: packages
- Release workflow → Native bundles: builds
- Release workflow → Python package: publishes