# akiriwas/visscreen architecture

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

- Interactive diagram: https://gitdiagram.com/akiriwas/visscreen
- Repository: https://github.com/akiriwas/visscreen

## Overview

1. **What this repository is**
   - VisScreen is a **local terminal UI application** for Linux that manages existing **GNU screen** sessions.
   - It is not a server/client app and has no database or network layer; the main external dependency is the local `screen` executable.

2. **Top-level structure**
   - `visscreen/app.py` is the **TUI application entrypoint** and likely owns the Textual app lifecycle, key bindings, and screen navigation.
   - `visscreen/manager.py` is the **command/adapter layer** that talks to GNU `screen`, parses session state, and performs operations like list, create, rejoin, detach, and kill.
   - `visscreen/renderers.py` is the **presentation layer** for formatting session data into widgets/panes for the TUI.
   - `visscreen/config.py` likely holds **runtime constants and UI/config defaults**.
   - `tests/test_manager.py` and `tests/test_tui.py` cover the core behavior and the UI integration points.

3. **Primary runtime flow**
   - On startup, the TUI app initializes and asks the manager for the current set of screen sessions.
   - The manager runs `screen` commands locally, converts their output into structured session records, and returns them to the UI.
   - The UI renders those records in a list plus a detail pane; user actions then flow back through the manager to execute the selected screen operation.

4. **Core subsystem boundary: UI vs session orchestration**
   - The **UI layer** (`app.py` + `renderers.py`) is responsible for interaction, filtering/search, selection state, and confirmation dialogs.
   - The **manager layer** (`manager.py`) is responsible for the semantics of screen session management and for isolating subprocess/CLI details from the UI.
   - This separation is important for the architecture: the TUI should not need to know GNU screen command syntax directly.

5. **Session model and data shape**
   - The README indicates each session has visible attributes such as **ID, name, timestamp, and state** (`Attached` / `Detached`).
   - That implies the manager normalizes raw `screen` output into a session object or dictionary-like record that the renderers can consume consistently.
   - The detail pane likely uses the same structured session data to show extended metadata.

6. **User interaction model**
   - The UI supports **search/fuzzy filtering**, **selection**, and **command shortcuts**:
     - Enter: rejoin selected session
     - `d`: detach and rejoin
     - `n`: create new named session
     - `k`: kill with confirmation
     - `r`: refresh list
     - `q`: quit
   - This makes the TUI event-driven: keystrokes mutate UI state, then call manager actions, then refresh the session list.

7. **Subprocess and system boundary**
   - The only meaningful external runtime boundary is the host system’s **GNU screen installation**.
   - All session operations are almost certainly implemented via local subprocess execution of `screen` commands, meaning the app depends on shell-level availability and Linux-like terminal behavior.
   - There are no indications of remote APIs, persistent storage, or background daemons.

8. **Rendering responsibilities**
   - `renderers.py` likely contains the logic for turning session objects into Textual components: list rows, detail views, status styling, and possibly empty/loading states.
   - This layer is distinct from the manager so the UI can re-render the same data in multiple places without re-parsing command output.

9. **Configuration and constants**
   - `config.py` likely centralizes things such as command names, key labels, UI text, and possibly default refresh or filtering behavior.
   - Keeping these values out of the app and manager reduces coupling and makes the TUI easier to adjust without changing business logic.

10. **Testing strategy**
   - `tests/test_manager.py` probably validates session parsing and command execution behavior, which is the highest-risk logic because it bridges Python and `screen` output.
   - `tests/test_tui.py` likely checks app-level behavior such as bindings, widget state updates, and reactions to user actions.
   - The tests suggest the repo treats **manager logic as the core domain layer** and the TUI as an interactive presentation shell.

11. **Packaging and toolchain**
   - The presence of `pyproject.toml` and `requirements.txt` indicates standard Python packaging plus dependency pinning.
   - The project is intended to be installed as a command-line entrypoint (`visscreen`) rather than imported as a library.

12. **Diagram-friendly summary**
   - A clear architecture diagram would show:
     - **Terminal user** interacting with
     - **Textual-based TUI app** (`app.py`)
     - which depends on
     - **renderer components** (`renderers.py`) for display and
     - **manager/services layer** (`manager.py`) for GNU screen orchestration
     - which talks to
     - **local GNU screen subprocesses / system terminal environment**
   - `config.py` sits as a shared support module feeding both UI and manager concerns, while tests verify the manager and app behavior separately.

Main entry points: [`visscreen/app.py`](https://github.com/akiriwas/visscreen/blob/master/visscreen/app.py) (TUI App), [`visscreen/manager.py`](https://github.com/akiriwas/visscreen/blob/master/visscreen/manager.py) (Manager), [`visscreen/renderers.py`](https://github.com/akiriwas/visscreen/blob/master/visscreen/renderers.py) (Renderers), [`tests/test_tui.py`](https://github.com/akiriwas/visscreen/blob/master/tests/test_tui.py) (TUI Tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interface"]
  node_user(("User<br/>operator"))
  node_app["TUI App<br/>Textual app<br/>[app.py]"]
  node_renderers["Renderers<br/>presentation<br/>[renderers.py]"]
end

subgraph group_orchestration["Orchestration"]
  node_manager["Manager<br/>screen adapter<br/>[manager.py]"]
end

subgraph group_support["Support"]
  node_session["Session Records<br/>normalized data"]
  node_config["Config<br/>defaults<br/>[config.py]"]
end

subgraph group_validation["Validation"]
  node_test_manager["Manager Tests<br/>pytest suite<br/>[test_manager.py]"]
  node_test_tui["TUI Tests<br/>pytest suite<br/>[test_tui.py]"]
end

subgraph group_external["External"]
  node_screen{{"GNU screen<br/>system CLI"}}
end

node_user -->|"keystrokes"| node_app
node_app -->|"render"| node_renderers
node_app -->|"actions"| node_manager
node_app -->|"defaults"| node_config
node_manager -->|"subprocess"| node_screen
node_manager -->|"normalize"| node_session
node_renderers -->|"display"| node_session
node_session -->|"state"| node_app
node_config -->|"settings"| node_manager
node_test_manager -.->|"covers"| node_manager
node_test_tui -.->|"covers"| node_app
node_test_tui -.->|"covers"| node_renderers

click node_app "https://github.com/akiriwas/visscreen/blob/master/visscreen/app.py"
click node_renderers "https://github.com/akiriwas/visscreen/blob/master/visscreen/renderers.py"
click node_manager "https://github.com/akiriwas/visscreen/blob/master/visscreen/manager.py"
click node_config "https://github.com/akiriwas/visscreen/blob/master/visscreen/config.py"
click node_test_manager "https://github.com/akiriwas/visscreen/blob/master/tests/test_manager.py"
click node_test_tui "https://github.com/akiriwas/visscreen/blob/master/tests/test_tui.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_user,node_app,node_renderers toneBlue
class node_manager toneAmber
class node_session,node_config toneMint
class node_test_manager,node_test_tui toneRose
class node_screen toneIndigo
```

## Components

### Interface

Terminal UI and presentation components

- **User**: operator · Terminal operator using the app
- [TUI App](https://github.com/akiriwas/visscreen/blob/master/visscreen/app.py): Textual app · Entry point, navigation, bindings, and UI state · `visscreen/app.py`
- [Renderers](https://github.com/akiriwas/visscreen/blob/master/visscreen/renderers.py): presentation · Builds list rows, detail panes, and status views · `visscreen/renderers.py`

### Orchestration

Session management and command execution

- [Manager](https://github.com/akiriwas/visscreen/blob/master/visscreen/manager.py): screen adapter · Runs screen commands and normalizes session operations · `visscreen/manager.py`

### Support

Shared configuration and data shape

- **Session Records**: normalized data · Structured session state shared between manager and UI
- [Config](https://github.com/akiriwas/visscreen/blob/master/visscreen/config.py): defaults · Shared constants and runtime/UI defaults · `visscreen/config.py`

### Validation

Test coverage for core behavior

- [Manager Tests](https://github.com/akiriwas/visscreen/blob/master/tests/test_manager.py): pytest suite · Parsing and command-behavior coverage · `tests/test_manager.py`
- [TUI Tests](https://github.com/akiriwas/visscreen/blob/master/tests/test_tui.py): pytest suite · App behavior and interaction coverage · `tests/test_tui.py`

### External

Host-provided GNU screen runtime

- **GNU screen**: system CLI · Local screen executable and terminal environment

## Connections

- User → TUI App: keystrokes · User interacts through the terminal UI
- TUI App → Renderers: render · App asks renderers to build the visible panes
- TUI App → Manager: actions · UI triggers refresh, join, detach, create, and kill flows
- TUI App → Config: defaults · App consumes shared labels and behavior constants
- Manager → GNU screen: subprocess · Manager invokes local GNU screen commands
- Manager → Session Records: normalize · Manager converts raw screen output into session records
- Renderers → Session Records: display · Renderers format structured session data for widgets
- Session Records → TUI App: state · App uses session data for selection and detail views
- Config → Manager: settings · Manager reads shared runtime defaults
- Manager Tests → Manager: covers · Validates command execution and parsing
- TUI Tests → TUI App: covers · Validates UI behavior and interactions
- TUI Tests → Renderers: covers · Checks presentation behavior
