# naos2w/naos-agent-stack architecture

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

- Interactive diagram: https://gitdiagram.com/naos2w/naos-agent-stack
- Repository: https://github.com/naos2w/naos-agent-stack

## Overview

Naos Agent Stack is a Windows PowerShell installer for OpenChatX Headless and Letta, with opt-in prerequisites, terminal customization, and two-PC shared-memory configuration. The documented workflow is to run the CLI, optionally preview a plan, install selected components after a read-only preflight and confirmation, then run a health check. The graph reflects README-documented behavior and paths visible in the tree; source excerpts were unavailable, so internal calls and implementation details are not inferred.

Main entry points: [`Engine.ps1`](https://github.com/naos2w/naos-agent-stack/blob/main/Engine.ps1) (Install engine), [`Install-Wizard.ps1`](https://github.com/naos2w/naos-agent-stack/blob/main/Install-Wizard.ps1) (Install wizard), [`naos-agent-stack.ps1`](https://github.com/naos2w/naos-agent-stack/blob/main/naos-agent-stack.ps1) (Stack CLI), [`Installer-Preflight.ps1`](https://github.com/naos2w/naos-agent-stack/blob/main/Installer-Preflight.ps1) (Asset preflight)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Installer workflow"]
  node_cli["Stack CLI"]
  node_plan["Plan preview"]
  node_wizard["Install wizard<br/>[Install-Wizard.ps1]"]
  node_preflight["Asset preflight"]
  node_engine["Install engine<br/>[Engine.ps1]"]
end

subgraph group_core["Core stack"]
  node_openchatx["OpenChatX Headless"]
  node_letta["Letta"]
  node_prerequisites["Node.js and npm<br/>[Prerequisites.ps1]"]
end

subgraph group_optional["Optional capabilities"]
  node_git["Optional Git<br/>[Prerequisites.ps1]"]
  node_terminal["Terminal enhancements"]
  node_shared["Shared-memory setup<br/>[Install-Wizard.ps1]"]
  node_tailscale["Tailscale"]
  node_openssh["Windows OpenSSH"]
end

subgraph group_operations["Operations"]
  node_doctor["Health check<br/>[Doctor.ps1]"]
end

node_user(("Windows user"))

node_user -->|"runs commands"| node_cli
node_cli -->|"previews plan"| node_plan
node_cli -->|"starts install"| node_wizard
node_wizard -->|"checks assets"| node_preflight
node_wizard -->|"installs selection"| node_engine
node_engine -->|"installs required"| node_openchatx
node_engine -->|"installs required"| node_letta
node_engine -->|"checks prerequisite"| node_prerequisites
node_engine -->|"offers opt-in"| node_git
node_engine -->|"offers opt-in"| node_terminal
node_wizard -->|"configures optionally"| node_shared
node_shared -->|"uses optionally"| node_tailscale
node_shared -->|"uses optionally"| node_openssh
node_user -->|"runs health check"| node_doctor

click node_cli "https://github.com/naos2w/naos-agent-stack/blob/main/naos-agent-stack.ps1"
click node_plan "https://github.com/naos2w/naos-agent-stack/blob/main/naos-agent-stack.ps1"
click node_wizard "https://github.com/naos2w/naos-agent-stack/blob/main/Install-Wizard.ps1"
click node_preflight "https://github.com/naos2w/naos-agent-stack/blob/main/Installer-Preflight.ps1"
click node_engine "https://github.com/naos2w/naos-agent-stack/blob/main/Engine.ps1"
click node_openchatx "https://github.com/naos2w/naos-agent-stack/blob/main/payload/bootstrap/naos-agent-stack.ps1"
click node_letta "https://github.com/naos2w/naos-agent-stack/blob/main/payload/bootstrap/naos-agent-stack.ps1"
click node_prerequisites "https://github.com/naos2w/naos-agent-stack/blob/main/Prerequisites.ps1"
click node_git "https://github.com/naos2w/naos-agent-stack/blob/main/Prerequisites.ps1"
click node_terminal "https://github.com/naos2w/naos-agent-stack/blob/main/Terminal-Extras.ps1"
click node_shared "https://github.com/naos2w/naos-agent-stack/blob/main/Install-Wizard.ps1"
click node_doctor "https://github.com/naos2w/naos-agent-stack/blob/main/Doctor.ps1"

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_plan,node_wizard,node_preflight,node_engine,node_user toneBlue
class node_openchatx,node_letta,node_prerequisites toneAmber
class node_git,node_terminal,node_shared,node_tailscale,node_openssh toneMint
class node_doctor toneRose
```

## Components

### Installer workflow

- [Stack CLI](https://github.com/naos2w/naos-agent-stack/blob/main/naos-agent-stack.ps1): `naos-agent-stack.ps1`
- [Plan preview](https://github.com/naos2w/naos-agent-stack/blob/main/naos-agent-stack.ps1): `naos-agent-stack.ps1`
- [Install wizard](https://github.com/naos2w/naos-agent-stack/blob/main/Install-Wizard.ps1): `Install-Wizard.ps1`
- [Asset preflight](https://github.com/naos2w/naos-agent-stack/blob/main/Installer-Preflight.ps1): `Installer-Preflight.ps1`
- [Install engine](https://github.com/naos2w/naos-agent-stack/blob/main/Engine.ps1): `Engine.ps1`

### Core stack

- [OpenChatX Headless](https://github.com/naos2w/naos-agent-stack/blob/main/payload/bootstrap/naos-agent-stack.ps1): `payload/bootstrap/naos-agent-stack.ps1`
- [Letta](https://github.com/naos2w/naos-agent-stack/blob/main/payload/bootstrap/naos-agent-stack.ps1): `payload/bootstrap/naos-agent-stack.ps1`
- [Node.js and npm](https://github.com/naos2w/naos-agent-stack/blob/main/Prerequisites.ps1): `Prerequisites.ps1`

### Optional capabilities

- [Optional Git](https://github.com/naos2w/naos-agent-stack/blob/main/Prerequisites.ps1): `Prerequisites.ps1`
- [Terminal enhancements](https://github.com/naos2w/naos-agent-stack/blob/main/Terminal-Extras.ps1): `Terminal-Extras.ps1`
- [Shared-memory setup](https://github.com/naos2w/naos-agent-stack/blob/main/Install-Wizard.ps1): `Install-Wizard.ps1`
- **Tailscale**
- **Windows OpenSSH**

### Operations

- [Health check](https://github.com/naos2w/naos-agent-stack/blob/main/Doctor.ps1): `Doctor.ps1`

### Other components

- **Windows user**

## Connections

- Windows user → Stack CLI: runs commands (evidence: `README.md`)
- Stack CLI → Plan preview: previews plan (evidence: `README.md`)
- Stack CLI → Install wizard: starts install (evidence: `README.md`)
- Install wizard → Asset preflight: checks assets (evidence: `README.md`)
- Install wizard → Install engine: installs selection (evidence: `README.md`)
- Install engine → OpenChatX Headless: installs required (evidence: `README.md`)
- Install engine → Letta: installs required (evidence: `README.md`)
- Install engine → Node.js and npm: checks prerequisite (evidence: `README.md`)
- Install engine → Optional Git: offers opt-in (evidence: `README.md`)
- Install engine → Terminal enhancements: offers opt-in (evidence: `README.md`)
- Install wizard → Shared-memory setup: configures optionally (evidence: `README.md`)
- Shared-memory setup → Tailscale: uses optionally (evidence: `README.md`)
- Shared-memory setup → Windows OpenSSH: uses optionally (evidence: `README.md`)
- Windows user → Health check: runs health check (evidence: `README.md`)