# soham1105-tech/orqen architecture

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

- Interactive diagram: https://gitdiagram.com/soham1105-tech/orqen
- Repository: https://github.com/soham1105-tech/orqen

## Overview

ORQEN is a repository-to-running-stack control plane with CLI, conversational-agent, and local web interfaces. Its main workflow resolves a local or Git source, discovers services and configuration, infers infrastructure, generates manifests, then builds, health-checks, and repairs the stack. Separate capabilities include in-container testing, interactive operations and dashboards, and ephemeral tunnels. The README documents the end-to-end workflow; source excerpts and the index support selected internal calls, but several command handlers and subsystems were not sampled.

Main entry points: [`cmd/init.go`](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/cmd/init.go) (Init workflow), [`internal/agent/agent.go`](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/agent/agent.go) (Intent agent), [`internal/scanner/scanner.go`](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/scanner/scanner.go) (Service scanner), [`cmd/chat.go`](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/cmd/chat.go) (Chat TUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Interfaces"]
  node_main["CLI entry<br/>[main.go]"]
  node_init["Init workflow<br/>[init.go]"]
  node_chat["Chat TUI<br/>[chat.go]"]
  node_web["Web control plane<br/>[server.go]"]
end

subgraph group_discovery["Project Discovery"]
  node_git["Source resolver<br/>[git.go]"]
  node_scanner["Service scanner<br/>[scanner.go]"]
  node_node["Node detection<br/>[node.go]"]
  node_python["Python detection<br/>[python.go]"]
  node_otherlangs["Go and Rust detection"]
  node_envvars["Env discovery<br/>[envvar.go]"]
end

subgraph group_stack["Stack Provisioning"]
  node_infra["Infrastructure inference<br/>[infra.go]"]
  node_generator["Manifest generation<br/>[generator.go]"]
  node_dockerfile["Dockerfile generation<br/>[dockerfile.go]"]
  node_state[("Project state<br/>[state.go]")]
end

subgraph group_operations["Runtime Operations"]
  node_docker["Compose operations<br/>[docker.go]"]
  node_health["Health checks<br/>[httpcheck.go]"]
  node_healer["Closed-loop repair<br/>[healer.go]"]
  node_testrun["In-container tests<br/>[testrun.go]"]
  node_dashboard["Live dashboard<br/>[dashboard.go]"]
  node_tunnel["Preview tunnel<br/>[tunnel.go]"]
end

subgraph group_agent["Agent and Web"]
  node_agent["Intent agent<br/>[agent.go]"]
  node_intent["Intent routing<br/>[intent.go]"]
  node_tools["Agent tools<br/>[tools.go]"]
  node_llm["LLM client<br/>[client.go]"]
  node_chatstore[("Chat persistence<br/>[store.go]")]
end

node_user(("Operator"))
node_docker_service["Docker Compose"]
node_llm_service["LLM provider"]
node_test_suite["Service test suite"]

node_user -->|"runs CLI"| node_main
node_main -.->|"selects command"| node_init
node_user -->|"starts conversation"| node_chat
node_user -->|"opens console"| node_web
node_init -->|"resolves source"| node_git
node_init -->|"scans services"| node_scanner
node_scanner -->|"detects Node"| node_node
node_scanner -->|"detects Python"| node_python
node_scanner -->|"detects Go Rust"| node_otherlangs
node_init -->|"discovers variables"| node_envvars
node_init -->|"infers services"| node_infra
node_init -->|"generates manifests"| node_generator
node_generator -->|"generates Dockerfiles"| node_dockerfile
node_init -->|"writes state"| node_state
node_init -->|"builds stack"| node_docker
node_docker -->|"invokes Compose"| node_docker_service
node_init -->|"verifies readiness"| node_health
node_init -->|"repairs failures"| node_healer
node_healer -->|"requests repair"| node_llm
node_healer -->|"checks HTTP"| node_health
node_user -->|"runs tests"| node_testrun
node_testrun -->|"executes in container"| node_test_suite
node_user -->|"opens dashboard"| node_dashboard
node_dashboard -->|"controls containers"| node_docker
node_chat -->|"runs intent"| node_agent
node_agent -->|"routes request"| node_intent
node_agent -->|"dispatches tools"| node_tools
node_agent -->|"calls model"| node_llm
node_llm -->|"sends HTTP request"| node_llm_service
node_web -->|"persists chats"| node_chatstore
node_web -->|"sends chat turn"| node_agent
node_chat -->|"starts preview"| node_tunnel

click node_main "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/main.go"
click node_init "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/cmd/init.go"
click node_chat "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/cmd/chat.go"
click node_web "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/web/server.go"
click node_git "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/git/git.go"
click node_scanner "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/scanner/scanner.go"
click node_node "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/scanner/node/node.go"
click node_python "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/scanner/python/python.go"
click node_otherlangs "https://github.com/soham1105-tech/orqen/tree/feat/orqen-rebrand-and-test/internal/scanner"
click node_envvars "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/envvar/envvar.go"
click node_infra "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/infra/infra.go"
click node_generator "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/generator/generator.go"
click node_dockerfile "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/generator/dockerfile.go"
click node_state "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/state/state.go"
click node_docker "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/docker/docker.go"
click node_health "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/httpcheck/httpcheck.go"
click node_healer "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/healer/healer.go"
click node_testrun "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/testrun/testrun.go"
click node_dashboard "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/dashboard/dashboard.go"
click node_agent "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/agent/agent.go"
click node_intent "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/agent/intent.go"
click node_tools "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/agent/tools.go"
click node_llm "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/llm/client.go"
click node_chatstore "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/web/store.go"
click node_tunnel "https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/tunnel/tunnel.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_main,node_init,node_chat,node_web toneBlue
class node_git,node_scanner,node_node,node_python,node_otherlangs,node_envvars toneAmber
class node_infra,node_generator,node_dockerfile,node_state toneMint
class node_docker,node_health,node_healer,node_testrun,node_dashboard,node_tunnel toneRose
class node_agent,node_intent,node_tools,node_llm,node_chatstore,node_user,node_docker_service,node_llm_service,node_test_suite toneIndigo
```

## Components

### User Interfaces

- [CLI entry](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/main.go): `main.go`
- [Init workflow](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/cmd/init.go): `cmd/init.go`
- [Chat TUI](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/cmd/chat.go): `cmd/chat.go`
- [Web control plane](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/web/server.go): `internal/web/server.go`

### Project Discovery

- [Source resolver](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/git/git.go): `internal/git/git.go`
- [Service scanner](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/scanner/scanner.go): `internal/scanner/scanner.go`
- [Node detection](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/scanner/node/node.go): `internal/scanner/node/node.go`
- [Python detection](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/scanner/python/python.go): `internal/scanner/python/python.go`
- [Go and Rust detection](https://github.com/soham1105-tech/orqen/tree/feat/orqen-rebrand-and-test/internal/scanner): `internal/scanner`
- [Env discovery](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/envvar/envvar.go): `internal/envvar/envvar.go`

### Stack Provisioning

- [Infrastructure inference](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/infra/infra.go): `internal/infra/infra.go`
- [Manifest generation](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/generator/generator.go): `internal/generator/generator.go`
- [Dockerfile generation](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/generator/dockerfile.go): `internal/generator/dockerfile.go`
- [Project state](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/state/state.go): `internal/state/state.go`

### Runtime Operations

- [Compose operations](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/docker/docker.go): `internal/docker/docker.go`
- [Health checks](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/httpcheck/httpcheck.go): `internal/httpcheck/httpcheck.go`
- [Closed-loop repair](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/healer/healer.go): `internal/healer/healer.go`
- [In-container tests](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/testrun/testrun.go): `internal/testrun/testrun.go`
- [Live dashboard](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/dashboard/dashboard.go): `internal/dashboard/dashboard.go`
- [Preview tunnel](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/tunnel/tunnel.go): `internal/tunnel/tunnel.go`

### Agent and Web

- [Intent agent](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/agent/agent.go): `internal/agent/agent.go`
- [Intent routing](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/agent/intent.go): `internal/agent/intent.go`
- [Agent tools](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/agent/tools.go): `internal/agent/tools.go`
- [LLM client](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/llm/client.go): `internal/llm/client.go`
- [Chat persistence](https://github.com/soham1105-tech/orqen/blob/feat/orqen-rebrand-and-test/internal/web/store.go): `internal/web/store.go`

### Other components

- **Operator**
- **Docker Compose**
- **LLM provider**
- **Service test suite**

## Connections

- Operator → CLI entry: runs CLI (evidence: `main.go`)
- CLI entry → Init workflow: selects command
- Operator → Chat TUI: starts conversation
- Operator → Web control plane: opens console
- Init workflow → Source resolver: resolves source
- Init workflow → Service scanner: scans services
- Service scanner → Node detection: detects Node (evidence: `internal/scanner/scanner.go`)
- Service scanner → Python detection: detects Python (evidence: `internal/scanner/scanner.go`)
- Service scanner → Go and Rust detection: detects Go Rust (evidence: `internal/scanner/scanner.go`)
- Init workflow → Env discovery: discovers variables
- Init workflow → Infrastructure inference: infers services
- Init workflow → Manifest generation: generates manifests
- Manifest generation → Dockerfile generation: generates Dockerfiles (evidence: `internal/generator/generator.go`)
- Init workflow → Project state: writes state
- Init workflow → Compose operations: builds stack
- Compose operations → Docker Compose: invokes Compose (evidence: `internal/docker/docker.go`)
- Init workflow → Health checks: verifies readiness
- Init workflow → Closed-loop repair: repairs failures
- Closed-loop repair → LLM client: requests repair (evidence: `internal/healer/healer.go`)
- Closed-loop repair → Health checks: checks HTTP (evidence: `internal/healer/healer.go`)
- Operator → In-container tests: runs tests
- In-container tests → Service test suite: executes in container
- Operator → Live dashboard: opens dashboard
- Live dashboard → Compose operations: controls containers (evidence: `internal/dashboard/dashboard.go`)
- Chat TUI → Intent agent: runs intent (evidence: `cmd/chat.go`)
- Intent agent → Intent routing: routes request (evidence: `internal/agent/agent.go`)
- Intent agent → Agent tools: dispatches tools (evidence: `internal/agent/agent.go`)
- Intent agent → LLM client: calls model (evidence: `internal/agent/agent.go`)
- LLM client → LLM provider: sends HTTP request (evidence: `internal/llm/client.go`)
- Web control plane → Chat persistence: persists chats (evidence: `internal/web/server.go`)
- Web control plane → Intent agent: sends chat turn (evidence: `internal/web/server.go`)
- Chat TUI → Preview tunnel: starts preview (evidence: `cmd/chat.go`)