# qarium/goga architecture

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

- Interactive diagram: https://gitdiagram.com/qarium/goga
- Repository: https://github.com/qarium/goga

## Overview

Goga is a CLI framework for reusable AI engineering processes. The main workflow is to configure a project, select a pipeline, resolve its workflow and stages, then launch an agent-driven run with optional human checkpoints. The graph also retains the documented tool-package and SDD-contract capabilities. Edges are limited to relationships supported by the README or SOURCE INDEX references; several subsystems are represented at directory level because their implementations were not sampled.

Main entry points: [`goga/pipeline/run_pipeline.py`](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/run_pipeline.py) (Run coordinator), [`goga/commands/pipeline/pipeline.py`](https://github.com/qarium/goga/blob/2.0.x/goga/commands/pipeline/pipeline.py) (Pipeline command), [`goga/commands/pipeline/run_pipeline_container.py`](https://github.com/qarium/goga/blob/2.0.x/goga/commands/pipeline/run_pipeline_container.py) (Docker launcher), [`goga/pipeline/list_pipelines.py`](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/list_pipelines.py) (Pipeline discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and setup"]
  node_cli["Goga CLI<br/>[cli.py]"]
  node_project_setup["Project setup<br/>[init.py]"]
  node_project_config["Project config<br/>[loader.py]"]
end

subgraph group_pipeline["Pipeline lifecycle"]
  node_pipeline_command["Pipeline command<br/>[pipeline.py]"]
  node_pipeline_discovery["Pipeline discovery<br/>[list_pipelines.py]"]
  node_pipeline_parser["Pipeline DSL parser<br/>[parse_dsl.py]"]
  node_pipeline_compiler["Flow compiler<br/>[compile_flow.py]"]
  node_workflow["Workflow resolution"]
  node_stage_controls["Stage controls"]
  node_pipeline_runner["Run coordinator<br/>[run_pipeline.py]"]
  node_docker_launcher["Docker launcher"]
  node_docker_runner["Docker execution<br/>[runner.py]"]
end

subgraph group_extension["Methodology extensions"]
  node_tools["Tool packages<br/>[registration.py]"]
  node_tool_catalog["Shared tool catalog<br/>[catalog.py]"]
  node_contracts["Language contracts"]
end

subgraph group_state["Project state"]
  node_history["Work history"]
  node_schema["Cell hierarchy<br/>[schema.py]"]
end

node_user(("Engineer"))
node_afm["AFM runtime"]
node_agent(("CLI agent"))

node_user -->|"invokes"| node_cli
node_cli -->|"routes commands"| node_pipeline_command
node_user -->|"initializes project"| node_project_setup
node_project_setup -.->|"configures project"| node_project_config
node_pipeline_command -->|"loads config"| node_project_config
node_pipeline_command -->|"launches run"| node_docker_launcher
node_pipeline_command -.->|"requests pipeline info"| node_pipeline_discovery
node_pipeline_discovery -->|"parses pipeline files"| node_pipeline_parser
node_pipeline_runner -->|"selects pipeline"| node_pipeline_discovery
node_pipeline_runner -->|"parses pipeline"| node_pipeline_parser
node_pipeline_runner -->|"resolves workflow"| node_workflow
node_pipeline_runner -->|"applies skips"| node_stage_controls
node_pipeline_runner -->|"compiles flow"| node_pipeline_compiler
node_pipeline_runner -->|"records run state"| node_history
node_docker_launcher -->|"runs container"| node_docker_runner
node_docker_launcher -->|"launches runtime"| node_afm
node_afm -->|"executes stages"| node_agent
node_user -->|"provides input"| node_agent
node_tools -.->|"registers packages"| node_tool_catalog
node_user -->|"installs capabilities"| node_tools
node_contracts -.->|"guides SDD cycle"| node_pipeline_runner
node_user -->|"inspects cells"| node_schema

click node_cli "https://github.com/qarium/goga/blob/2.0.x/goga/cli.py"
click node_project_setup "https://github.com/qarium/goga/blob/2.0.x/goga/commands/init/init.py"
click node_project_config "https://github.com/qarium/goga/blob/2.0.x/goga/config/project/loader.py"
click node_pipeline_command "https://github.com/qarium/goga/blob/2.0.x/goga/commands/pipeline/pipeline.py"
click node_pipeline_discovery "https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/list_pipelines.py"
click node_pipeline_parser "https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/compiler/parse_dsl.py"
click node_pipeline_compiler "https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/compiler/compile_flow.py"
click node_workflow "https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/resolve_workflow.py"
click node_stage_controls "https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/apply_skip_stages.py"
click node_pipeline_runner "https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/run_pipeline.py"
click node_docker_launcher "https://github.com/qarium/goga/blob/2.0.x/goga/commands/pipeline/run_pipeline_container.py"
click node_docker_runner "https://github.com/qarium/goga/blob/2.0.x/goga/docker/runner.py"
click node_tools "https://github.com/qarium/goga/blob/2.0.x/goga/hooks/tools/registration.py"
click node_tool_catalog "https://github.com/qarium/goga/blob/2.0.x/goga/hooks/catalog/catalog.py"
click node_contracts "https://github.com/qarium/goga/tree/2.0.x/goga/contract"
click node_history "https://github.com/qarium/goga/tree/2.0.x/goga/history"
click node_schema "https://github.com/qarium/goga/blob/2.0.x/goga/schema/schema.py"

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_cli,node_project_setup,node_project_config toneBlue
class node_pipeline_command,node_pipeline_discovery,node_pipeline_parser,node_pipeline_compiler,node_workflow,node_stage_controls,node_pipeline_runner,node_docker_launcher,node_docker_runner toneAmber
class node_tools,node_tool_catalog,node_contracts toneMint
class node_history,node_schema toneRose
class node_user,node_afm,node_agent toneIndigo
```

## Components

### CLI and setup

- [Goga CLI](https://github.com/qarium/goga/blob/2.0.x/goga/cli.py): `goga/cli.py`
- [Project setup](https://github.com/qarium/goga/blob/2.0.x/goga/commands/init/init.py): `goga/commands/init/init.py`
- [Project config](https://github.com/qarium/goga/blob/2.0.x/goga/config/project/loader.py): `goga/config/project/loader.py`

### Pipeline lifecycle

- [Pipeline command](https://github.com/qarium/goga/blob/2.0.x/goga/commands/pipeline/pipeline.py): `goga/commands/pipeline/pipeline.py`
- [Pipeline discovery](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/list_pipelines.py): `goga/pipeline/list_pipelines.py`
- [Pipeline DSL parser](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/compiler/parse_dsl.py): `goga/pipeline/compiler/parse_dsl.py`
- [Flow compiler](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/compiler/compile_flow.py): `goga/pipeline/compiler/compile_flow.py`
- [Workflow resolution](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/resolve_workflow.py): `goga/pipeline/resolve_workflow.py`
- [Stage controls](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/apply_skip_stages.py): `goga/pipeline/apply_skip_stages.py`
- [Run coordinator](https://github.com/qarium/goga/blob/2.0.x/goga/pipeline/run_pipeline.py): `goga/pipeline/run_pipeline.py`
- [Docker launcher](https://github.com/qarium/goga/blob/2.0.x/goga/commands/pipeline/run_pipeline_container.py): `goga/commands/pipeline/run_pipeline_container.py`
- [Docker execution](https://github.com/qarium/goga/blob/2.0.x/goga/docker/runner.py): `goga/docker/runner.py`

### Methodology extensions

- [Tool packages](https://github.com/qarium/goga/blob/2.0.x/goga/hooks/tools/registration.py): `goga/hooks/tools/registration.py`
- [Shared tool catalog](https://github.com/qarium/goga/blob/2.0.x/goga/hooks/catalog/catalog.py): `goga/hooks/catalog/catalog.py`
- [Language contracts](https://github.com/qarium/goga/tree/2.0.x/goga/contract): `goga/contract`

### Project state

- [Work history](https://github.com/qarium/goga/tree/2.0.x/goga/history): `goga/history`
- [Cell hierarchy](https://github.com/qarium/goga/blob/2.0.x/goga/schema/schema.py): `goga/schema/schema.py`

### Other components

- **Engineer**
- **AFM runtime**
- **CLI agent**

## Connections

- Engineer → Goga CLI: invokes
- Goga CLI → Pipeline command: routes commands (evidence: `goga/cli.py`)
- Engineer → Project setup: initializes project
- Project setup → Project config: configures project
- Pipeline command → Project config: loads config (evidence: `goga/commands/pipeline/pipeline.py`)
- Pipeline command → Docker launcher: launches run (evidence: `goga/commands/pipeline/pipeline.py`)
- Pipeline command → Pipeline discovery: requests pipeline info
- Pipeline discovery → Pipeline DSL parser: parses pipeline files (evidence: `goga/pipeline/describe_pipelines.py`)
- Run coordinator → Pipeline discovery: selects pipeline (evidence: `goga/pipeline/run_pipeline.py`)
- Run coordinator → Pipeline DSL parser: parses pipeline (evidence: `goga/pipeline/run_pipeline.py`)
- Run coordinator → Workflow resolution: resolves workflow (evidence: `goga/pipeline/run_pipeline.py`)
- Run coordinator → Stage controls: applies skips (evidence: `goga/pipeline/run_pipeline.py`)
- Run coordinator → Flow compiler: compiles flow (evidence: `goga/pipeline/run_pipeline.py`)
- Run coordinator → Work history: records run state (evidence: `goga/pipeline/run_pipeline.py`)
- Docker launcher → Docker execution: runs container (evidence: `goga/commands/pipeline/run_pipeline_container.py`)
- Docker launcher → AFM runtime: launches runtime (evidence: `goga/commands/pipeline/run_pipeline_container.py`)
- AFM runtime → CLI agent: executes stages
- Engineer → CLI agent: provides input
- Tool packages → Shared tool catalog: registers packages
- Engineer → Tool packages: installs capabilities
- Language contracts → Run coordinator: guides SDD cycle
- Engineer → Cell hierarchy: inspects cells
