# greyhoundforty/tengingarstjori architecture

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

- Interactive diagram: https://gitdiagram.com/greyhoundforty/tengingarstjori
- Repository: https://github.com/greyhoundforty/tengingarstjori

## Overview

##### Project Type and Purpose
- Tengingarstjóri is a standalone Python CLI/TUI application (a command-line SSH connection manager) packaged as a library for import and as an executable `tg` command.
- Purpose: allow users to manage SSH connections (add, list, remove, show, tunnel, proxy-jump) via a clean CLI interface while storing state in a managed SSH config file and a JSON data store.

##### File Structure Analysis
- Top-level:
- Configuration and metadata (pyproject.toml, setup files, workflows, scripts, docs)
- `main.py` – CLI entrypoint
- `src/` – application code plus top-level `cli.py`, `config_manager.py`, `models.py`, `exceptions.py`, and `setup.py`
- `src/tengingarstjori/` – the same modules under the package namespace (real library code)
- `tests/` – unit and integration tests for each module and feature
- `scripts/` – automation: build, test, formatting, packaging
- Architectural patterns:
- Layered structure: CLI layer → domain/API layer → persistence layer → external systems
- Separation of concerns: `cli.py` handles parsing; `config_manager.py` handles business logic; `models.py` defines data objects; file I/O and SSH external calls are encapsulated in the manager.

##### README Insights
- Core architecture described in README under “Architecture”:
1. Managed SSH config file (`~/.ssh/config.tengingarstjori`)
2. Inclusion into main SSH config
3. Persistent JSON store at `~/.tengingarstjori/connections.json`
4. Non-invasive integration
- Features list highlights key components: CLI commands, proxy-jump, port forwarding, JSON output, Python API.

a. Main Components
- User Terminal (shell)
- CLI Interface (`tg` / `main.py`)
- Application Layer (`tengingarstjori.cli` → `tengingarstjori.config_manager`)
- Data Models (`SSHConnection`, settings, exceptions)
- Persistence Layer
- JSON Store (`~/.tengingarstjori/connections.json`)
- Managed SSH Config File (`~/.ssh/config.tengingarstjori`)
- External Systems
- Native SSH binary (`ssh`)
- User’s original SSH config (`~/.ssh/config`)
b. Relationships & Interactions
- User invokes `tg <command>` → CLI layer parses command → calls methods on `SSHConfigManager`
- Manager reads/writes the JSON store and updates the managed SSH config file
- On `tg connect` (or underlying `ssh <host>`), CLI may shell out to the SSH binary, passing host alias
- Backup and reset commands interact with user’s original config (create backups, restore)
c. Architectural Patterns & Principles
- Layering: clear CLI vs. business logic vs. persistence
- Single Responsibility: each module has one role (parsing, data validation, I/O)
- Non-invasive integration: isolation of managed config
- Extensibility: Python API for programmatic use
d. Key Technologies & Libraries
- Python standard library: `argparse` or `click`, `json`, `pathlib`, `subprocess`
- Packaging: `pyproject.toml`, `setuptools`, `wheel`
- Testing: `pytest`, bespoke test scripts, CI workflows (.github/workflows)
- Linting & formatting: flake8, black, pre-commit

##### Detailed Capture of Architectural Elements
- Both the packaging/deployment side (PyPI package, CI workflows) and the runtime side (CLI & library).
- Separate the code modules into logical layers.
- Avoid over-segmenting; focus on the main 5–7 components listed above and their interactions.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Runtime Flow
    UserShell["User Terminal (Shell)"]:::external
    CLIEntrypoint["tg (main.py)"]:::python_module
    CLI1["cli.py"]:::python_module
    CLI2["tengingarstjori/cli.py"]:::python_module
    ConfigMgr1["config_manager.py"]:::python_module
    ConfigMgr2["tengingarstjori/config_manager.py"]:::python_module
    Models1["models.py"]:::python_module
    Models2["tengingarstjori/models.py"]:::python_module
    Exceptions1["exceptions.py"]:::python_module
    Exceptions2["tengingarstjori/exceptions.py"]:::python_module
    JSONStore["JSON Store (~/.tengingarstjori/connections.json)"]:::persistence
    SSHConfigFile["Managed SSH Config (~/.ssh/config.tengingarstjori)"]:::persistence
    SSHBinary["SSH Binary"]:::external
    UserSSHConfig["User SSH Config (~/.ssh/config)"]:::external

    UserShell -->|"invoke tg command"| CLIEntrypoint
    CLIEntrypoint -->|"parses commands"| CLI1
    CLIEntrypoint -->|"parses commands"| CLI2
    CLI1 -->|"dispatch to manager"| ConfigMgr1
    CLI2 -->|"dispatch to manager"| ConfigMgr2
    ConfigMgr1 -->|"uses data models"| Models1
    ConfigMgr1 -->|"handles errors"| Exceptions1
    ConfigMgr2 -->|"uses data models"| Models2
    ConfigMgr2 -->|"handles errors"| Exceptions2
    ConfigMgr1 -->|"write/read"| JSONStore
    ConfigMgr1 -->|"write config"| SSHConfigFile
    ConfigMgr2 -->|"write/read"| JSONStore
    ConfigMgr2 -->|"write config"| SSHConfigFile
    CLIEntrypoint -->|"ssh <host> call"| SSHBinary
    SSHConfigFile -->|"Included via `Include` directive`"| UserSSHConfig

    %% Packaging & CI
    subgraph "Packaging & CI"
        PyProject["pyproject.toml"]:::packaging
        Setup1["src/setup.py"]:::packaging
        Setup2["src/tengingarstjori/setup.py"]:::packaging
        TestCI[".github/workflows/test.yml"]:::ci
        PublishCI[".github/workflows/publish.yml"]:::ci
    end
    CLIEntrypoint -->|packaging metadata| PyProject
    PyProject -->|installable package| Setup1
    Setup1 --> Setup2
    SetupCI["CI Trigger"]:::ci --> TestCI
    SetupCI --> PublishCI

    %% Automation Scripts
    subgraph "Automation Scripts"
        ScriptsDir["scripts/"]:::script
    end
    ScriptsDir --> TestCI
    ScriptsDir --> PublishCI

    %% Tests
    subgraph "Tests"
        TestsDir["tests/"]:::test
    end
    TestsDir --> CLI1
    TestsDir --> ConfigMgr1
    TestsDir --> Models1
    TestsDir --> Exceptions1

    %% Documentation
    subgraph "Documentation"
        Readme["README.md"]:::doc
        DocsDir["docs/"]:::doc
    end
    Readme --> CLIEntrypoint
    DocsDir --> PyProject

    %% Click Events
    click CLIEntrypoint "https://github.com/greyhoundforty/tengingarstjori/blob/main/main.py"
    click CLI1 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/cli.py"
    click CLI2 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/tengingarstjori/cli.py"
    click ConfigMgr1 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/config_manager.py"
    click ConfigMgr2 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/tengingarstjori/config_manager.py"
    click Models1 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/models.py"
    click Models2 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/tengingarstjori/models.py"
    click Exceptions1 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/exceptions.py"
    click Exceptions2 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/tengingarstjori/exceptions.py"
    click PyProject "https://github.com/greyhoundforty/tengingarstjori/blob/main/pyproject.toml"
    click Setup1 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/setup.py"
    click Setup2 "https://github.com/greyhoundforty/tengingarstjori/blob/main/src/tengingarstjori/setup.py"
    click TestCI "https://github.com/greyhoundforty/tengingarstjori/blob/main/.github/workflows/test.yml"
    click PublishCI "https://github.com/greyhoundforty/tengingarstjori/blob/main/.github/workflows/publish.yml"
    click ScriptsDir "https://github.com/greyhoundforty/tengingarstjori/tree/main/scripts/"
    click TestsDir "https://github.com/greyhoundforty/tengingarstjori/tree/main/tests/"
    click Readme "https://github.com/greyhoundforty/tengingarstjori/blob/main/README.md"
    click DocsDir "https://github.com/greyhoundforty/tengingarstjori/tree/main/docs/"

    %% Styles
    classDef python_module fill:#D6E9C6,stroke:#3C763D,color:#3C763D;
    classDef persistence fill:#F2DEDE,stroke:#A94442,color:#A94442;
    classDef external fill:#D9EDF7,stroke:#31708F,color:#31708F;
    classDef packaging fill:#FCF8E3,stroke:#8A6D3B,color:#8A6D3B;
    classDef ci fill:#EEE,stroke:#666,color:#666,stroke-dasharray: 5 5;
    classDef script fill:#F5F5F5,stroke:#999,color:#999,stroke-dasharray: 2 2;
    classDef test fill:#FFF2CC,stroke:#996600,color:#996600;
    classDef doc fill:#EBF4FA,stroke:#31708F,color:#31708F;
```
