# baibhab-adhikari/naturally-linux architecture

> Architecture diagram of the GitHub repository baibhab-adhikari/naturally-linux, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/baibhab-adhikari/naturally-linux
- Repository: https://github.com/baibhab-adhikari/naturally-linux

## Overview

1. **What this repo is**
   - `naturally-linux` is a Python CLI that converts a user’s natural-language prompt into a Linux shell command, then shows the command, explains it, applies safety checks, and only executes after confirmation.
   - The architecture is centered around a linear “prompt → generated command → safety review → optional execution” flow.

2. **Primary runtime boundary**
   - The main user entrypoint is the CLI, exposed through `main.py`, `naturally_linux/__main__.py`, and `naturally_linux/cli.py`.
   - This is not a service or daemon; it is a local, interactive command-line application.

3. **CLI orchestration layer**
   - `naturally_linux/cli.py` is the top-level coordinator.
   - It likely parses subcommands and flags such as `--dry-run`, `--timeout`, and `config ...`, then routes work to the generator, safety, config, and executor subsystems.
   - This layer owns the user interaction boundary: prompt input, command preview, explanation display, and confirmation before execution.

4. **Command generation subsystem**
   - `naturally_linux/generator.py` is the AI-backed translation layer from natural language to shell command.
   - The README indicates it uses a Groq API key, so this module is the external LLM boundary.
   - The output of this subsystem is a proposed shell command plus explanatory text used by the CLI before any execution happens.

5. **Safety subsystem**
   - `naturally_linux/safety.py` is the guardrail layer between generation and execution.
   - Its job is to inspect the proposed command for unsafe patterns, risky operations, or other disallowed behavior before execution is permitted.
   - This is a key architectural boundary: even if generation produces a command, safety can block it.

6. **Execution subsystem**
   - `naturally_linux/executor.py` is responsible for actually running the command on the local system.
   - It sits behind both the safety checks and the explicit user confirmation step.
   - The README’s timeout option suggests execution is time-bounded, so this module likely handles process invocation and termination policy.

7. **Configuration and secrets**
   - `naturally_linux/config.py` handles persistent CLI configuration, especially the Groq API key.
   - The repo supports both environment-based configuration (`GROQ_API_KEY`) and CLI-managed storage via `naturally-linux config set-key/show/delete`.
   - This module is the boundary between application logic and local user configuration/secrets management.

8. **End-to-end data flow**
   - User types a request in the CLI.
   - The CLI reads configuration, sends the request to the generator, receives a proposed command and explanation, runs safety validation, and presents the result.
   - If not in dry-run mode and the user confirms, the executor runs the command locally; otherwise the flow stops after preview.

9. **Dry-run and review-first behavior**
   - The architecture explicitly supports a non-executing preview path (`--dry-run`).
   - This means command generation and explanation are reusable outputs independent of execution, which is important for safe review and for testing the generation path without side effects.

10. **Testing boundaries**
   - `tests/test_generator.py`, `tests/test_safety.py`, and `tests/test_executor.py` map directly to the three main logic subsystems.
   - That separation suggests each core module is designed with a narrow responsibility and can be tested independently from the CLI shell.

11. **Packaging and runtime/tooling**
   - `pyproject.toml` and `uv.lock` show a packaged Python project intended for installation as a tool.
   - The presence of `.python-version` suggests a pinned Python runtime, and the README recommends `uv tool install naturally-linux`, so distribution is built around standard Python packaging rather than a custom installer.

12. **Docs and operational guidance**
   - `docs/` and `mkdocs.yml` indicate the project has a documentation site with architecture, installation, safety, FAQ, and usage guidance.
   - The docs likely mirror the code boundaries: how to install, how prompts flow through generation/safety/execution, and how safety constraints are intended to be used.

13. **CI/release pipeline**
   - `.github/workflows/ci.yml` and `.github/workflows/release.yml` provide repository-level automation for validation and publishing.
   - These pipelines are part of the engineering boundary around the CLI package, not the runtime behavior of the tool itself.

14. **Architecture summary**
   - The key diagram should show one local CLI process orchestrating four internal modules: config, generator, safety, and executor.
   - The only notable external dependency in the runtime path is the Groq API used for command generation; everything else is local to the user’s machine.

Main entry points: [`naturally_linux/cli.py`](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/cli.py) (CLI), [`naturally_linux/generator.py`](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/generator.py) (Generator), [`pyproject.toml`](https://github.com/baibhab-adhikari/naturally-linux/blob/main/pyproject.toml) (Package), [`main.py`](https://github.com/baibhab-adhikari/naturally-linux/blob/main/main.py) (main.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main_py["main.py<br/>entrypoint<br/>[main.py]"]
  node_module_main["__main__<br/>entrypoint<br/>[__main__.py]"]
  node_cli["CLI<br/>orchestrator<br/>[cli.py]"]
  node_config["Config<br/>settings store<br/>[config.py]"]
  node_generator["Generator<br/>llm translator<br/>[generator.py]"]
  node_groq_api(("Groq API<br/>external api"))
  node_safety{{"Safety<br/>guardrail<br/>[safety.py]"}}
  node_executor["Executor<br/>process runner<br/>[executor.py]"]
  node_prompt["User prompt<br/>input"]
  node_review["Review<br/>confirmation"]
end

subgraph group_project["Project"]
  node_python_pkg["Package<br/>python project<br/>[pyproject.toml]"]
  node_lockfile["Lockfile<br/>dependency lock<br/>[uv.lock]"]
  node_version["Python version<br/>runtime pin<br/>[.python-version]"]
end

subgraph group_docs["Docs"]
  node_docs_home["Docs<br/>documentation<br/>[index.md]"]
  node_architecture_doc["Architecture<br/>doc page<br/>[architecture.md]"]
end

subgraph group_ci["CI/CD"]
  node_ci_workflow["CI<br/>workflow<br/>[ci.yml]"]
  node_release_workflow["Release<br/>workflow<br/>[release.yml]"]
end

node_main_py -->|"launches"| node_cli
node_module_main -->|"invokes"| node_cli
node_prompt -->|"enters"| node_cli
node_cli -->|"reads"| node_config
node_config -->|"provides key"| node_generator
node_cli -->|"requests"| node_generator
node_generator -->|"calls"| node_groq_api
node_groq_api -->|"returns"| node_generator
node_generator -->|"hands off"| node_safety
node_safety -->|"approves or blocks"| node_cli
node_cli -->|"shows"| node_review
node_review -->|"confirms"| node_cli
node_cli -->|"executes"| node_executor
node_executor -->|"returns result"| node_cli
node_cli -.->|"dry-run"| node_review
node_python_pkg -->|"packages"| node_main_py
node_lockfile -->|"pins deps"| node_python_pkg
node_version -->|"pins runtime"| node_python_pkg
node_docs_home -->|"links"| node_architecture_doc
node_ci_workflow -->|"validates"| node_python_pkg
node_release_workflow -->|"publishes"| node_python_pkg

click node_main_py "https://github.com/baibhab-adhikari/naturally-linux/blob/main/main.py"
click node_module_main "https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/__main__.py"
click node_cli "https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/cli.py"
click node_config "https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/config.py"
click node_generator "https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/generator.py"
click node_safety "https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/safety.py"
click node_executor "https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/executor.py"
click node_python_pkg "https://github.com/baibhab-adhikari/naturally-linux/blob/main/pyproject.toml"
click node_lockfile "https://github.com/baibhab-adhikari/naturally-linux/blob/main/uv.lock"
click node_version "https://github.com/baibhab-adhikari/naturally-linux/blob/main/.python-version"
click node_docs_home "https://github.com/baibhab-adhikari/naturally-linux/blob/main/docs/index.md"
click node_architecture_doc "https://github.com/baibhab-adhikari/naturally-linux/blob/main/docs/architecture.md"
click node_ci_workflow "https://github.com/baibhab-adhikari/naturally-linux/blob/main/.github/workflows/ci.yml"
click node_release_workflow "https://github.com/baibhab-adhikari/naturally-linux/blob/main/.github/workflows/release.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_main_py,node_module_main,node_cli,node_config,node_generator,node_groq_api,node_safety,node_executor,node_prompt,node_review toneBlue
class node_python_pkg,node_lockfile,node_version toneAmber
class node_docs_home,node_architecture_doc toneMint
class node_ci_workflow,node_release_workflow toneRose
```

## Components

### Runtime

Local command-line execution path

- [main.py](https://github.com/baibhab-adhikari/naturally-linux/blob/main/main.py): entrypoint · Top-level launcher for the CLI · `main.py`
- [__main__](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/__main__.py): entrypoint · Module entrypoint for `python -m` invocation · `naturally_linux/__main__.py`
- [CLI](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/cli.py): orchestrator · Parses arguments and coordinates the user flow · `naturally_linux/cli.py`
- [Config](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/config.py): settings store · Loads and manages API key and local settings · `naturally_linux/config.py`
- [Generator](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/generator.py): llm translator · Converts natural language into a shell command and explanation · `naturally_linux/generator.py`
- **Groq API**: external api · Remote LLM boundary used for command generation
- [Safety](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/safety.py): guardrail · Checks proposed commands for risky or disallowed behavior · `naturally_linux/safety.py`
- [Executor](https://github.com/baibhab-adhikari/naturally-linux/blob/main/naturally_linux/executor.py): process runner · Runs approved commands locally with timeout handling · `naturally_linux/executor.py`
- **User prompt**: input · Natural-language request entered in the terminal
- **Review**: confirmation · Displays command and explanation for user approval

### Project

Repository packaging and supporting assets

- [Package](https://github.com/baibhab-adhikari/naturally-linux/blob/main/pyproject.toml): python project · Packaged CLI distribution and dependency metadata · `pyproject.toml`
- [Lockfile](https://github.com/baibhab-adhikari/naturally-linux/blob/main/uv.lock): dependency lock · Pinned dependency resolution for reproducible installs · `uv.lock`
- [Python version](https://github.com/baibhab-adhikari/naturally-linux/blob/main/.python-version): runtime pin · Pinned interpreter version for local development · `.python-version`

### Docs

User-facing documentation

- [Docs](https://github.com/baibhab-adhikari/naturally-linux/blob/main/docs/index.md): documentation · Project documentation site and usage guidance · `docs/index.md`
- [Architecture](https://github.com/baibhab-adhikari/naturally-linux/blob/main/docs/architecture.md): doc page · Explains the system boundaries and command flow · `docs/architecture.md`

### CI/CD

Automated validation and release workflows

- [CI](https://github.com/baibhab-adhikari/naturally-linux/blob/main/.github/workflows/ci.yml): workflow · Automated validation pipeline · `.github/workflows/ci.yml`
- [Release](https://github.com/baibhab-adhikari/naturally-linux/blob/main/.github/workflows/release.yml): workflow · Publishing and release automation · `.github/workflows/release.yml`

## Connections

- main.py → CLI: launches · Starts the interactive application
- __main__ → CLI: invokes · Enables module-based entrypoint
- User prompt → CLI: enters · User request is passed into the CLI
- CLI → Config: reads · Loads API key and local settings
- Config → Generator: provides key · Supplies credentials for generation
- CLI → Generator: requests · Sends prompt for command generation
- Generator → Groq API: calls · Uses remote LLM service to infer command
- Groq API → Generator: returns · Provides proposed command and explanation
- Generator → Safety: hands off · Proposed command is reviewed before execution
- Safety → CLI: approves or blocks · Returns safety decision to the coordinator
- CLI → Review: shows · Presents command and explanation to the user
- Review → CLI: confirms · User approves or cancels execution
- CLI → Executor: executes · Runs the command only after safety and confirmation
- Executor → CLI: returns result · Reports output, status, or timeout outcome
- CLI → Review: dry-run · Preview-only path skips execution
- Package → main.py: packages · Defines the installable CLI entrypoint
- Lockfile → Package: pins deps · Supports reproducible installs
- Python version → Package: pins runtime · Records target Python version
- Docs → Architecture: links · Documentation site includes architecture guidance
- CI → Package: validates · Runs repository checks for the package
- Release → Package: publishes · Handles release automation for the package
