# mrazeekk/alex-cli architecture

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

- Interactive diagram: https://gitdiagram.com/mrazeekk/alex-cli
- Repository: https://github.com/mrazeekk/alex-cli

## Overview

Alex is a Debian-focused terminal assistant. Users request help or error analysis through the CLI; Alex asks OpenAI for structured guidance, displays proposed commands, and—when requested and approved—executes them with risk checks. Separate CLI paths cover service diagnosis, key/configuration management, and system health checks. The shell hook supplies failed-command context for error analysis. The graph reflects documented capabilities and shown imports/calls; unsampled behavior is represented only where the README documents it.

Main entry points: [`alex/cli.py`](https://github.com/mrazeekk/alex-cli/blob/main/alex/cli.py) (Command interface), [`alex/openai_client.py`](https://github.com/mrazeekk/alex-cli/blob/main/alex/openai_client.py) (Structured AI client), [`alex/service_diag.py`](https://github.com/mrazeekk/alex-cli/blob/main/alex/service_diag.py) (Service diagnosis), [`alex/doctor.py`](https://github.com/mrazeekk/alex-cli/blob/main/alex/doctor.py) (System doctor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["CLI workflows"]
  node_cli["Command interface<br/>[cli.py]"]
  node_errorlog["Failed-command log"]
  node_hook["Shell error hook<br/>[alex-shell-hook.sh]"]
  node_errorreader["Error log filtering<br/>[errors.py]"]
end

subgraph group_diagnosis["Diagnostics"]
  node_service["Service diagnosis<br/>[service_diag.py]"]
  node_resolver["Service name resolver<br/>[service_resolve.py]"]
  node_doctor["System doctor<br/>[doctor.py]"]
  node_systemd["Systemd and journal"]
end

subgraph group_ai["AI and presentation"]
  node_ai_client["Structured AI client<br/>[openai_client.py]"]
  node_openai["OpenAI API"]
  node_schema["Response schema<br/>[schema.py]"]
  node_system_info["System information<br/>[system.py]"]
  node_renderer["Response renderer<br/>[render.py]"]
end

subgraph group_settings["Credentials and settings"]
  node_auth["API key management<br/>[auth.py]"]
  node_keyfile["Stored API key"]
  node_keyguard["Key availability check<br/>[utils.py]"]
  node_userconfig["User preferences<br/>[user_config.py]"]
  node_defaults["Default settings<br/>[config.py]"]
end

subgraph group_execution["System execution"]
  node_executor["Command executor<br/>[executor.py]"]
end

node_user(("Terminal user"))

node_user -->|"invokes"| node_cli
node_hook -->|"records failures"| node_errorlog
node_cli -->|"reads and filters"| node_errorreader
node_cli -->|"reads error context"| node_errorlog
node_cli -->|"checks key"| node_keyguard
node_cli -->|"requests analysis"| node_ai_client
node_cli -->|"runs approved commands"| node_executor
node_cli -->|"renders guidance"| node_renderer
node_cli -->|"starts diagnosis"| node_service
node_cli -->|"resolves service name"| node_resolver
node_cli -->|"runs checks"| node_doctor
node_cli -->|"manages credentials"| node_auth
node_cli -->|"edits preferences"| node_userconfig
node_service -->|"runs probes"| node_executor
node_service -->|"queries unit and logs"| node_systemd
node_service -->|"requests next probes"| node_ai_client
node_service -->|"renders findings"| node_renderer
node_resolver -->|"lists service units"| node_executor
node_doctor -->|"checks key status"| node_auth
node_doctor -->|"checks config path"| node_userconfig
node_doctor -->|"prints results"| node_renderer
node_ai_client -->|"sends structured request"| node_openai
node_ai_client -->|"gets response schema"| node_schema
node_ai_client -->|"gets system context"| node_system_info
node_ai_client -->|"loads preferences"| node_userconfig
node_ai_client -->|"uses model default"| node_defaults
node_auth -->|"reads and writes"| node_keyfile
node_keyguard -->|"loads key into environment"| node_auth

click node_cli "https://github.com/mrazeekk/alex-cli/blob/main/alex/cli.py"
click node_hook "https://github.com/mrazeekk/alex-cli/blob/main/scripts/alex-shell-hook.sh"
click node_errorreader "https://github.com/mrazeekk/alex-cli/blob/main/alex/errors.py"
click node_service "https://github.com/mrazeekk/alex-cli/blob/main/alex/service_diag.py"
click node_resolver "https://github.com/mrazeekk/alex-cli/blob/main/alex/service_resolve.py"
click node_doctor "https://github.com/mrazeekk/alex-cli/blob/main/alex/doctor.py"
click node_ai_client "https://github.com/mrazeekk/alex-cli/blob/main/alex/openai_client.py"
click node_schema "https://github.com/mrazeekk/alex-cli/blob/main/alex/schema.py"
click node_system_info "https://github.com/mrazeekk/alex-cli/blob/main/alex/system.py"
click node_renderer "https://github.com/mrazeekk/alex-cli/blob/main/alex/render.py"
click node_executor "https://github.com/mrazeekk/alex-cli/blob/main/alex/executor.py"
click node_auth "https://github.com/mrazeekk/alex-cli/blob/main/alex/auth.py"
click node_keyguard "https://github.com/mrazeekk/alex-cli/blob/main/alex/utils.py"
click node_userconfig "https://github.com/mrazeekk/alex-cli/blob/main/alex/user_config.py"
click node_defaults "https://github.com/mrazeekk/alex-cli/blob/main/alex/config.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_errorlog,node_hook,node_errorreader,node_user toneBlue
class node_service,node_resolver,node_doctor,node_systemd toneAmber
class node_ai_client,node_openai,node_schema,node_system_info,node_renderer toneMint
class node_auth,node_keyfile,node_keyguard,node_userconfig,node_defaults toneRose
class node_executor toneIndigo
```

## Components

### CLI workflows

- [Command interface](https://github.com/mrazeekk/alex-cli/blob/main/alex/cli.py): `alex/cli.py`
- **Failed-command log**
- [Shell error hook](https://github.com/mrazeekk/alex-cli/blob/main/scripts/alex-shell-hook.sh): `scripts/alex-shell-hook.sh`
- [Error log filtering](https://github.com/mrazeekk/alex-cli/blob/main/alex/errors.py): `alex/errors.py`

### Diagnostics

- [Service diagnosis](https://github.com/mrazeekk/alex-cli/blob/main/alex/service_diag.py): `alex/service_diag.py`
- [Service name resolver](https://github.com/mrazeekk/alex-cli/blob/main/alex/service_resolve.py): `alex/service_resolve.py`
- [System doctor](https://github.com/mrazeekk/alex-cli/blob/main/alex/doctor.py): `alex/doctor.py`
- **Systemd and journal**

### AI and presentation

- [Structured AI client](https://github.com/mrazeekk/alex-cli/blob/main/alex/openai_client.py): `alex/openai_client.py`
- **OpenAI API**
- [Response schema](https://github.com/mrazeekk/alex-cli/blob/main/alex/schema.py): `alex/schema.py`
- [System information](https://github.com/mrazeekk/alex-cli/blob/main/alex/system.py): `alex/system.py`
- [Response renderer](https://github.com/mrazeekk/alex-cli/blob/main/alex/render.py): `alex/render.py`

### Credentials and settings

- [API key management](https://github.com/mrazeekk/alex-cli/blob/main/alex/auth.py): `alex/auth.py`
- **Stored API key**
- [Key availability check](https://github.com/mrazeekk/alex-cli/blob/main/alex/utils.py): `alex/utils.py`
- [User preferences](https://github.com/mrazeekk/alex-cli/blob/main/alex/user_config.py): `alex/user_config.py`
- [Default settings](https://github.com/mrazeekk/alex-cli/blob/main/alex/config.py): `alex/config.py`

### System execution

- [Command executor](https://github.com/mrazeekk/alex-cli/blob/main/alex/executor.py): `alex/executor.py`

### Other components

- **Terminal user**

## Connections

- Terminal user → Command interface: invokes (evidence: `README.md`)
- Shell error hook → Failed-command log: records failures (evidence: `README.md`)
- Command interface → Error log filtering: reads and filters (evidence: `alex/cli.py`)
- Command interface → Failed-command log: reads error context (evidence: `README.md`)
- Command interface → Key availability check: checks key (evidence: `alex/cli.py`)
- Command interface → Structured AI client: requests analysis (evidence: `alex/cli.py`)
- Command interface → Command executor: runs approved commands (evidence: `alex/cli.py`)
- Command interface → Response renderer: renders guidance (evidence: `alex/cli.py`)
- Command interface → Service diagnosis: starts diagnosis (evidence: `alex/cli.py`)
- Command interface → Service name resolver: resolves service name (evidence: `alex/cli.py`)
- Command interface → System doctor: runs checks (evidence: `alex/cli.py`)
- Command interface → API key management: manages credentials (evidence: `alex/cli.py`)
- Command interface → User preferences: edits preferences (evidence: `alex/cli.py`)
- Service diagnosis → Command executor: runs probes (evidence: `alex/service_diag.py`)
- Service diagnosis → Systemd and journal: queries unit and logs (evidence: `alex/service_diag.py`)
- Service diagnosis → Structured AI client: requests next probes (evidence: `alex/service_diag.py`)
- Service diagnosis → Response renderer: renders findings (evidence: `alex/service_diag.py`)
- Service name resolver → Command executor: lists service units (evidence: `alex/service_resolve.py`)
- System doctor → API key management: checks key status (evidence: `alex/doctor.py`)
- System doctor → User preferences: checks config path (evidence: `alex/doctor.py`)
- System doctor → Response renderer: prints results (evidence: `alex/doctor.py`)
- Structured AI client → OpenAI API: sends structured request (evidence: `alex/openai_client.py`)
- Structured AI client → Response schema: gets response schema (evidence: `alex/openai_client.py`)
- Structured AI client → System information: gets system context (evidence: `alex/openai_client.py`)
- Structured AI client → User preferences: loads preferences (evidence: `alex/openai_client.py`)
- Structured AI client → Default settings: uses model default (evidence: `alex/openai_client.py`)
- API key management → Stored API key: reads and writes (evidence: `alex/auth.py`)
- Key availability check → API key management: loads key into environment (evidence: `alex/utils.py`)
