# taasezer/taanos architecture

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

- Interactive diagram: https://gitdiagram.com/taasezer/taanos
- Repository: https://github.com/taasezer/taanos

## Overview

1. **Overall shape**
   TaaNOS is a single Go CLI application with a thin command entrypoint and a set of internal subsystems that form a deterministic execution pipeline. The design goal is explicit in the README: AI is used only to infer intent, while actual system actions come from a hardcoded registry.

2. **CLI entrypoint and command surface**
   `cmd/taanos/main.go` is the executable entrypoint. It likely wires CLI commands such as `init`, `status`, `history`, `model`, `config`, and `version`, plus mode flags like explain/guided/auto and dry-run. This layer is the user-facing boundary; everything else sits behind it.

3. **Pipeline as the core orchestration boundary**
   `internal/pipeline` is the central coordinator. It defines stage abstractions and pipeline-level errors, which suggests the app is built as a sequence of well-defined phases rather than ad hoc command handling. This is the main structure you would diagram: request enters, moves through stages, then either executes or stops with validation/recovery.

4. **Intent extraction is the only AI-facing step**
   `internal/intent` contains `extractor.go`, `prompt.go`, `validator.go`, and intent types. This subsystem turns natural language into a structured intent, probably via a local Ollama model as described in the README. Importantly, this layer does not execute commands; it only produces a normalized intent that downstream deterministic stages can consume.

5. **Planner and deterministic action registry**
   `internal/planner` contains `planner.go`, `registry.go`, `templates.go`, and types. This is the deterministic mapping layer from intent to executable plan. The presence of a registry indicates fixed action definitions, and templates suggest it can render command sequences or step descriptions from those registered actions. This is the key safety boundary between interpretation and execution.

6. **Validation and safety gating**
   `internal/validator` implements a separate safety gate, while `internal/intent/validator.go` likely validates extracted intent shape or confidence. The README’s “7-stage validator” implies multiple checks, such as privilege, disk space, dependency/tool presence, and risk assessment. Architecturally, validation sits between planning and execution and can block unsafe requests before any system mutation occurs.

7. **Execution and rollback**
   `internal/executor` runs the approved plan, while `internal/recovery` provides rollback logic if a step fails. This split suggests forward execution and inverse actions are modeled separately, which is important for a diagram: execution is not just “run commands,” it is paired with compensating recovery steps to preserve system safety.

8. **Context gathering and caching**
   `internal/context` includes `analyzer.go`, `cache.go`, and types. This subsystem likely collects system facts used by intent analysis, planning, and validation, and caches them to avoid repeated probing. It is the read-only observational layer feeding the rest of the pipeline with environment state.

9. **OS and environment abstraction**
   `internal/os` contains platform detection and per-OS implementations for Linux, macOS, Windows, network, and system info. This is where cross-platform differences are normalized. It likely powers checks such as virtualization detection, RAM detection, package-manager availability, and root/admin privilege inspection, all of which affect setup and validation decisions.

10. **User interaction and mode control**
   `internal/interaction` handles confirmations, prompts, and the guided/auto/explain behavior described in the README. This layer sits between pipeline stages and the user, controlling whether a step is merely described, explicitly approved, or automatically advanced.

11. **Persistence and audit trail**
   `internal/history` stores execution records, and the README says this is backed by SQLite. That persistence layer records intent, outcomes, duration, and risk profile so the CLI can show past operations and provide traceability. For an architecture diagram, this is the durable audit boundary separate from the live execution path.

12. **Setup and first-run bootstrap**
   `internal/setup` contains OS-specific detection plus a wizard. This subsystem is distinct from normal command execution: it initializes Ollama, selects an appropriate model, and configures the environment on first run. The bootstrap flow depends heavily on platform detection and machine characteristics.

13. **Cross-cutting config and logging**
   `config` holds defaults and runtime configuration, while `internal/logger` standardizes log output and verbosity. These are cross-cutting support layers used throughout the CLI and pipeline, not standalone business subsystems.

14. **Important external dependencies**
   The main external runtime dependency is **Ollama**, used locally for intent extraction. The rest of the system is intentionally deterministic and local: system commands, platform inspection, and SQLite-backed history are all part of the local machine boundary. The repository also includes installation scripts for Linux/macOS and Windows, plus packaged binaries, which support distribution but do not change the core architecture.

Main entry points: [`internal/intent/extractor.go`](https://github.com/taasezer/taanos/blob/main/internal/intent/extractor.go) (Intent), [`cmd/taanos/main.go`](https://github.com/taasezer/taanos/blob/main/cmd/taanos/main.go) (Main CLI), [`internal/pipeline/pipeline.go`](https://github.com/taasezer/taanos/blob/main/internal/pipeline/pipeline.go) (Pipeline), [`internal/context/analyzer.go`](https://github.com/taasezer/taanos/blob/main/internal/context/analyzer.go) (Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cmd_main["Main CLI<br/>entrypoint<br/>[main.go]"]
end

subgraph group_core["Core pipeline"]
  node_pipeline_core["Pipeline<br/>orchestrator<br/>[pipeline.go]"]
  node_pipeline_stage["Stages<br/>stage API<br/>[stage.go]"]
  node_intent_extract["Intent<br/>[extractor.go]"]
  node_intent_prompt["Prompt<br/>[prompt.go]"]
  node_intent_validate["Intent check<br/>validation<br/>[validator.go]"]
  node_planner_core["Planner<br/>mapping<br/>[planner.go]"]
  node_planner_registry[("Registry<br/>actions<br/>[registry.go]")]
  node_validator_core{{"Safety gate<br/>policy<br/>[validator.go]"}}
  node_executor_core["Executor<br/>runner<br/>[executor.go]"]
  node_recovery_core["Recovery<br/>rollback<br/>[recovery.go]"]
end

subgraph group_support["Support"]
  node_config_defaults["Config<br/>settings<br/>[defaults.go]"]
  node_config_runtime["Runtime config<br/>settings<br/>[config.go]"]
  node_interaction_core["Interaction<br/>ui control<br/>[interaction.go]"]
  node_history_store[("History<br/>audit store<br/>[store.go]")]
  node_context_core["Context<br/>environment<br/>[analyzer.go]"]
  node_logger_core["Logger<br/>logging<br/>[logger.go]"]
end

subgraph group_platform["Platform"]
  node_os_detect["OS detect<br/>platform detection<br/>[detect.go]"]
  node_setup_wizard["Setup<br/>bootstrap<br/>[wizard.go]"]
end

node_cmd_main -->|"loads"| node_config_runtime
node_cmd_main -->|"uses"| node_logger_core
node_cmd_main -->|"drives"| node_interaction_core
node_cmd_main -->|"starts"| node_pipeline_core
node_pipeline_core -->|"runs"| node_pipeline_stage
node_pipeline_core -->|"reads"| node_context_core
node_pipeline_core -->|"requests"| node_intent_extract
node_intent_extract -->|"builds"| node_intent_prompt
node_intent_extract -->|"produces"| node_intent_validate
node_intent_extract -->|"consults"| node_context_core
node_intent_extract -->|"consults"| node_os_detect
node_intent_validate -->|"passes"| node_planner_core
node_planner_core -->|"resolves"| node_planner_registry
node_planner_core -->|"submits"| node_validator_core
node_validator_core -->|"asks"| node_interaction_core
node_validator_core -->|"approves"| node_executor_core
node_executor_core -->|"guards"| node_recovery_core
node_executor_core -->|"records"| node_history_store
node_setup_wizard -->|"detects"| node_os_detect
node_setup_wizard -->|"probes"| node_context_core
node_context_core -->|"gathers"| node_os_detect
node_config_runtime -->|"inherits"| node_config_defaults

click node_cmd_main "https://github.com/taasezer/taanos/blob/main/cmd/taanos/main.go"
click node_config_defaults "https://github.com/taasezer/taanos/blob/main/config/defaults.go"
click node_config_runtime "https://github.com/taasezer/taanos/blob/main/config/config.go"
click node_pipeline_core "https://github.com/taasezer/taanos/blob/main/internal/pipeline/pipeline.go"
click node_pipeline_stage "https://github.com/taasezer/taanos/blob/main/internal/pipeline/stage.go"
click node_intent_extract "https://github.com/taasezer/taanos/blob/main/internal/intent/extractor.go"
click node_intent_prompt "https://github.com/taasezer/taanos/blob/main/internal/intent/prompt.go"
click node_intent_validate "https://github.com/taasezer/taanos/blob/main/internal/intent/validator.go"
click node_planner_core "https://github.com/taasezer/taanos/blob/main/internal/planner/planner.go"
click node_planner_registry "https://github.com/taasezer/taanos/blob/main/internal/planner/registry.go"
click node_validator_core "https://github.com/taasezer/taanos/blob/main/internal/validator/validator.go"
click node_executor_core "https://github.com/taasezer/taanos/blob/main/internal/executor/executor.go"
click node_recovery_core "https://github.com/taasezer/taanos/blob/main/internal/recovery/recovery.go"
click node_interaction_core "https://github.com/taasezer/taanos/blob/main/internal/interaction/interaction.go"
click node_history_store "https://github.com/taasezer/taanos/blob/main/internal/history/store.go"
click node_context_core "https://github.com/taasezer/taanos/blob/main/internal/context/analyzer.go"
click node_os_detect "https://github.com/taasezer/taanos/blob/main/internal/os/detect.go"
click node_setup_wizard "https://github.com/taasezer/taanos/blob/main/internal/setup/wizard.go"
click node_logger_core "https://github.com/taasezer/taanos/blob/main/internal/logger/logger.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_cmd_main toneBlue
class node_pipeline_core,node_pipeline_stage,node_intent_extract,node_intent_prompt,node_intent_validate,node_planner_core,node_planner_registry,node_validator_core,node_executor_core,node_recovery_core toneAmber
class node_config_defaults,node_config_runtime,node_interaction_core,node_history_store,node_context_core,node_logger_core toneMint
class node_os_detect,node_setup_wizard toneRose
```

## Components

### CLI

User-facing entrypoint and command surface.

- [Main CLI](https://github.com/taasezer/taanos/blob/main/cmd/taanos/main.go): entrypoint · Executable entrypoint and command wiring. · `cmd/taanos/main.go`

### Core pipeline

Deterministic request-to-action flow.

- [Pipeline](https://github.com/taasezer/taanos/blob/main/internal/pipeline/pipeline.go): orchestrator · Coordinates the staged execution flow. · `internal/pipeline/pipeline.go`
- [Stages](https://github.com/taasezer/taanos/blob/main/internal/pipeline/stage.go): stage API · Stage abstraction used by the pipeline. · `internal/pipeline/stage.go`
- [Intent](https://github.com/taasezer/taanos/blob/main/internal/intent/extractor.go): ai intent · Extracts structured intent from natural language. · `internal/intent/extractor.go`
- [Prompt](https://github.com/taasezer/taanos/blob/main/internal/intent/prompt.go): ai prompt · Prompt construction for intent inference. · `internal/intent/prompt.go`
- [Intent check](https://github.com/taasezer/taanos/blob/main/internal/intent/validator.go): validation · Validates extracted intent shape and quality. · `internal/intent/validator.go`
- [Planner](https://github.com/taasezer/taanos/blob/main/internal/planner/planner.go): mapping · Turns intent into an executable plan. · `internal/planner/planner.go`
- [Registry](https://github.com/taasezer/taanos/blob/main/internal/planner/registry.go): actions · Hardcoded action registry for deterministic execution. · `internal/planner/registry.go`
- [Safety gate](https://github.com/taasezer/taanos/blob/main/internal/validator/validator.go): policy · Runs repository safety and feasibility checks. · `internal/validator/validator.go`
- [Executor](https://github.com/taasezer/taanos/blob/main/internal/executor/executor.go): runner · Executes approved plan steps. · `internal/executor/executor.go`
- [Recovery](https://github.com/taasezer/taanos/blob/main/internal/recovery/recovery.go): rollback · Compensating actions and rollback handling. · `internal/recovery/recovery.go`

### Support

Cross-cutting services and persistence.

- [Config](https://github.com/taasezer/taanos/blob/main/config/defaults.go): settings · Runtime defaults and configuration values. · `config/defaults.go`
- [Runtime config](https://github.com/taasezer/taanos/blob/main/config/config.go): settings · Config loading and access helpers. · `config/config.go`
- [Interaction](https://github.com/taasezer/taanos/blob/main/internal/interaction/interaction.go): ui control · Prompts, confirmations, and mode control. · `internal/interaction/interaction.go`
- [History](https://github.com/taasezer/taanos/blob/main/internal/history/store.go): audit store · SQLite-backed execution history and traceability. · `internal/history/store.go`
- [Context](https://github.com/taasezer/taanos/blob/main/internal/context/analyzer.go): environment · Collects and caches machine state for decisions. · `internal/context/analyzer.go`
- [Logger](https://github.com/taasezer/taanos/blob/main/internal/logger/logger.go): logging · Shared logging and verbosity control. · `internal/logger/logger.go`

### Platform

OS detection and environment-specific setup.

- [OS detect](https://github.com/taasezer/taanos/blob/main/internal/os/detect.go): platform detection · Normalizes platform and system information. · `internal/os/detect.go`
- [Setup](https://github.com/taasezer/taanos/blob/main/internal/setup/wizard.go): bootstrap · First-run detection and environment bootstrap. · `internal/setup/wizard.go`

## Connections

- Main CLI → Runtime config: loads · CLI initializes runtime configuration.
- Main CLI → Logger: uses · CLI establishes logging early.
- Main CLI → Interaction: drives · CLI routes user-facing modes and prompts.
- Main CLI → Pipeline: starts · CLI hands requests to the pipeline.
- Pipeline → Stages: runs · Pipeline executes ordered stages.
- Pipeline → Context: reads · Pipeline consumes system context.
- Pipeline → Intent: requests · Pipeline begins by extracting intent.
- Intent → Prompt: builds · Prompting supports the AI intent step.
- Intent → Intent check: produces · Extracted intent is normalized and checked.
- Intent → Context: consults · Intent extraction can use gathered context.
- Intent → OS detect: consults · Platform facts may inform inference.
- Intent check → Planner: passes · Validated intent is handed to planning.
- Planner → Registry: resolves · Planner maps intent through fixed actions.
- Planner → Safety gate: submits · Planned actions are checked for safety.
- Safety gate → Interaction: asks · Safety decisions may require confirmation.
- Safety gate → Executor: approves · Approved plans proceed to execution.
- Executor → Recovery: guards · Failures trigger rollback handling.
- Executor → History: records · Execution outcomes are persisted for audit.
- Setup → OS detect: detects · Bootstrap uses OS and machine detection.
- Setup → Context: probes · Setup inspects environment capabilities.
- Context → OS detect: gathers · Context analysis relies on platform data.
- Runtime config → Config: inherits · Runtime configuration starts from defaults.
