# ar4mirez/samuel architecture

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

- Interactive diagram: https://gitdiagram.com/ar4mirez/samuel
- Repository: https://github.com/ar4mirez/samuel

## Overview

Samuel is a Go CLI framework manager and autonomous AI coding loop. Its principal workflow initializes a project with framework guidance, lets users discover and add components, then bootstraps and runs task-driven coding iterations with status and task-management commands. Separate CLI capabilities handle updates, health checks, configuration, synchronization, and version comparisons; the v4 orchestrator installs the gstack, gbrain, and Samuel-skills bundle. The README documents these product flows; source excerpts confirm selected command-to-core calls, while unsampled command internals are represented only where documented.

Main entry points: [`internal/commands/root.go`](https://github.com/ar4mirez/samuel/blob/main/internal/commands/root.go) (Command router), [`internal/commands/auto.go`](https://github.com/ar4mirez/samuel/blob/main/internal/commands/auto.go) (Run lifecycle commands), [`internal/orchestrator/orchestrator.go`](https://github.com/ar4mirez/samuel/blob/main/internal/orchestrator/orchestrator.go) (Bundle orchestrator), [`internal/core/registry.go`](https://github.com/ar4mirez/samuel/blob/main/internal/core/registry.go) (Framework content)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI workflows"]
  node_entry["CLI entry<br/>[main.go]"]
  node_commands["Command router<br/>[root.go]"]
  node_discovery["Component discovery<br/>[search.go]"]
  node_ui["CLI output<br/>[output.go]"]
end

subgraph group_loop["Autonomous loop"]
  node_run_commands["Run lifecycle commands<br/>[auto.go]"]
  node_task_commands["Task management"]
  node_loop_engine["Iteration engine<br/>[auto_loop.go]"]
  node_task_state[("PRD and task state<br/>[auto_tasks.go]")]
end

subgraph group_framework["Framework management"]
  node_component_ops["Component add/remove<br/>[add.go]"]
  node_initialization["Project initialization<br/>[init.go]"]
  node_framework_store[("Framework content<br/>[registry.go]")]
  node_update["Framework update<br/>[update.go]"]
  node_health["Installation health<br/>[doctor.go]"]
  node_admin["Admin operations<br/>[admin.go]"]
  node_sync["Folder synchronization<br/>[sync.go]"]
end

subgraph group_orchestration["Install orchestration"]
  node_orchestrator["Bundle orchestrator<br/>[orchestrator.go]"]
  node_bundle_parts["Bundle components"]
  node_skills["Embedded skills<br/>[embed.go]"]
end

node_user(("Project user"))
node_coding_agent(("AI coding tool"))

node_user -->|"invokes"| node_entry
node_entry -->|"executes"| node_commands
node_commands -.->|"routes discovery"| node_discovery
node_commands -.->|"routes changes"| node_component_ops
node_commands -.->|"routes init"| node_initialization
node_commands -.->|"routes update"| node_update
node_commands -.->|"routes checks"| node_health
node_commands -.->|"routes admin"| node_admin
node_discovery -->|"searches catalog"| node_framework_store
node_component_ops -.->|"manages components"| node_framework_store
node_initialization -.->|"installs framework"| node_framework_store
node_update -->|"updates framework"| node_framework_store
node_health -->|"checks bundle"| node_orchestrator
node_admin -.->|"runs sync"| node_sync
node_initialization -->|"installs bundle"| node_orchestrator
node_orchestrator -->|"installs components"| node_bundle_parts
node_orchestrator -->|"uses embedded content"| node_skills
node_user -->|"starts loop"| node_run_commands
node_run_commands -->|"runs iterations"| node_loop_engine
node_run_commands -->|"loads loop state"| node_task_state
node_task_commands -->|"reads and updates"| node_task_state
node_loop_engine -->|"invokes coding tool"| node_coding_agent
node_run_commands -->|"reports status"| node_ui

click node_entry "https://github.com/ar4mirez/samuel/blob/main/cmd/samuel/main.go"
click node_commands "https://github.com/ar4mirez/samuel/blob/main/internal/commands/root.go"
click node_discovery "https://github.com/ar4mirez/samuel/blob/main/internal/commands/search.go"
click node_component_ops "https://github.com/ar4mirez/samuel/blob/main/internal/commands/add.go"
click node_initialization "https://github.com/ar4mirez/samuel/blob/main/internal/commands/init.go"
click node_framework_store "https://github.com/ar4mirez/samuel/blob/main/internal/core/registry.go"
click node_update "https://github.com/ar4mirez/samuel/blob/main/internal/commands/update.go"
click node_health "https://github.com/ar4mirez/samuel/blob/main/internal/commands/doctor.go"
click node_admin "https://github.com/ar4mirez/samuel/blob/main/internal/commands/admin.go"
click node_sync "https://github.com/ar4mirez/samuel/blob/main/internal/core/sync.go"
click node_orchestrator "https://github.com/ar4mirez/samuel/blob/main/internal/orchestrator/orchestrator.go"
click node_bundle_parts "https://github.com/ar4mirez/samuel/blob/main/internal/orchestrator/component_samuel.go"
click node_skills "https://github.com/ar4mirez/samuel/blob/main/internal/skills/embed.go"
click node_run_commands "https://github.com/ar4mirez/samuel/blob/main/internal/commands/auto.go"
click node_task_commands "https://github.com/ar4mirez/samuel/blob/main/internal/commands/auto_task_handlers.go"
click node_loop_engine "https://github.com/ar4mirez/samuel/blob/main/internal/core/auto_loop.go"
click node_task_state "https://github.com/ar4mirez/samuel/blob/main/internal/core/auto_tasks.go"
click node_ui "https://github.com/ar4mirez/samuel/blob/main/internal/ui/output.go"

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_commands,node_discovery,node_ui,node_user toneBlue
class node_run_commands,node_task_commands,node_loop_engine,node_task_state toneAmber
class node_component_ops,node_initialization,node_framework_store,node_update,node_health,node_admin,node_sync toneMint
class node_orchestrator,node_bundle_parts,node_skills toneRose
class node_coding_agent toneIndigo
```

## Components

### CLI workflows

- [CLI entry](https://github.com/ar4mirez/samuel/blob/main/cmd/samuel/main.go): `cmd/samuel/main.go`
- [Command router](https://github.com/ar4mirez/samuel/blob/main/internal/commands/root.go): `internal/commands/root.go`
- [Component discovery](https://github.com/ar4mirez/samuel/blob/main/internal/commands/search.go): `internal/commands/search.go`
- [CLI output](https://github.com/ar4mirez/samuel/blob/main/internal/ui/output.go): `internal/ui/output.go`

### Autonomous loop

- [Run lifecycle commands](https://github.com/ar4mirez/samuel/blob/main/internal/commands/auto.go): `internal/commands/auto.go`
- [Task management](https://github.com/ar4mirez/samuel/blob/main/internal/commands/auto_task_handlers.go): `internal/commands/auto_task_handlers.go`
- [Iteration engine](https://github.com/ar4mirez/samuel/blob/main/internal/core/auto_loop.go): `internal/core/auto_loop.go`
- [PRD and task state](https://github.com/ar4mirez/samuel/blob/main/internal/core/auto_tasks.go): `internal/core/auto_tasks.go`

### Framework management

- [Component add/remove](https://github.com/ar4mirez/samuel/blob/main/internal/commands/add.go): `internal/commands/add.go`
- [Project initialization](https://github.com/ar4mirez/samuel/blob/main/internal/commands/init.go): `internal/commands/init.go`
- [Framework content](https://github.com/ar4mirez/samuel/blob/main/internal/core/registry.go): `internal/core/registry.go`
- [Framework update](https://github.com/ar4mirez/samuel/blob/main/internal/commands/update.go): `internal/commands/update.go`
- [Installation health](https://github.com/ar4mirez/samuel/blob/main/internal/commands/doctor.go): `internal/commands/doctor.go`
- [Admin operations](https://github.com/ar4mirez/samuel/blob/main/internal/commands/admin.go): `internal/commands/admin.go`
- [Folder synchronization](https://github.com/ar4mirez/samuel/blob/main/internal/core/sync.go): `internal/core/sync.go`

### Install orchestration

- [Bundle orchestrator](https://github.com/ar4mirez/samuel/blob/main/internal/orchestrator/orchestrator.go): `internal/orchestrator/orchestrator.go`
- [Bundle components](https://github.com/ar4mirez/samuel/blob/main/internal/orchestrator/component_samuel.go): `internal/orchestrator/component_samuel.go`
- [Embedded skills](https://github.com/ar4mirez/samuel/blob/main/internal/skills/embed.go): `internal/skills/embed.go`

### Other components

- **Project user**
- **AI coding tool**

## Connections

- Project user → CLI entry: invokes
- CLI entry → Command router: executes (evidence: `cmd/samuel/main.go`)
- Command router → Component discovery: routes discovery
- Command router → Component add/remove: routes changes
- Command router → Project initialization: routes init
- Command router → Framework update: routes update
- Command router → Installation health: routes checks
- Command router → Admin operations: routes admin
- Component discovery → Framework content: searches catalog (evidence: `internal/commands/search.go`)
- Component add/remove → Framework content: manages components
- Project initialization → Framework content: installs framework
- Framework update → Framework content: updates framework (evidence: `internal/commands/update.go`)
- Installation health → Bundle orchestrator: checks bundle
- Admin operations → Folder synchronization: runs sync
- Project initialization → Bundle orchestrator: installs bundle
- Bundle orchestrator → Bundle components: installs components
- Bundle orchestrator → Embedded skills: uses embedded content
- Project user → Run lifecycle commands: starts loop
- Run lifecycle commands → Iteration engine: runs iterations
- Run lifecycle commands → PRD and task state: loads loop state
- Task management → PRD and task state: reads and updates (evidence: `internal/commands/auto_task_handlers.go`)
- Iteration engine → AI coding tool: invokes coding tool
- Run lifecycle commands → CLI output: reports status
