# hbisneto/supernanno architecture

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

- Interactive diagram: https://gitdiagram.com/hbisneto/supernanno
- Repository: https://github.com/hbisneto/supernanno

## Overview

1. **Entry points and runtime**
   - The package starts through `supernanno/__main__.py` and `supernanno/app.py`, which bootstrap the Textual TUI application.
   - Command-line parsing lives under `supernanno/cli/`, so startup decisions like file path, read-only mode, line jump, and search seed happen before the UI is mounted.

2. **Top-level architecture**
   - The repository is organized into a clear split between **UI**, **event handling**, **services**, **core business logic**, and **search/state subsystems**.
   - The core design is service-oriented and event-driven: widgets emit events, events are handled by dedicated modules, and the handlers delegate into services/core rather than embedding logic in UI components.

3. **Application façade**
   - `supernanno/services/app_context.py` is the central boundary object.
   - It acts as the shared access point for configuration, logging, error handling, session state, file operations, and other cross-cutting concerns, reducing direct coupling between UI widgets and lower-level logic.

4. **UI layer**
   - `supernanno/ui/` contains the Textual widgets and layouts: editor layout, search bar, startup view, and settings screen.
   - `style.tcss` defines the terminal styling, while `ui/bindings.py` centralizes keyboard shortcuts.
   - This layer is presentation-focused; it routes user actions outward instead of owning business rules.

5. **Event-driven interaction flow**
   - User input is translated into Textual events under `supernanno/events/` such as key presses, button clicks, input changes, mount/unmount, and file-tree selection.
   - These events are handled by focused modules in `supernanno/handlers/` for high-level actions like opening files, quitting, and toggling the sidebar.
   - This creates a one-way flow: UI → event → handler → service/core logic → UI/status update.

6. **Core editing and file operations**
   - `supernanno/core/editor.py` and `supernanno/core/file_manager.py` are the main editing backend.
   - `FileManager` owns file I/O and backup behavior; the README indicates atomic save semantics via temp-file-then-rename and `.bak` creation before overwrite.
   - `core/status.py`, `core/logger.py`, and `core/structured_logger.py` support editor feedback and structured observability, while remaining separate from the widget tree.

7. **Search subsystem**
   - Search is isolated under `supernanno/search/` and uses a strategy pattern.
   - `registry.py` selects a strategy at runtime, `strategies.py` implements literal/case-sensitive/regex modes, `engine.py` performs matching, and `controller.py` coordinates UI actions and search state.
   - Search state is tracked separately in `supernanno/states/search.py`, which keeps search mode and results distinct from the editor buffer.

8. **Configuration and settings**
   - The app consumes two config layers: declarative `.supernannorc` parsing and structured `config.json` runtime settings.
   - `supernanno/services/rc_parser.py`, `config_manager.py`, and `config_applier.py` load and merge settings; `paths.py` resolves platform-specific config locations.
   - The README’s async watcher implies config changes can be hot-reloaded, so config is a live input to the app rather than a startup-only concern.
   - `supernanno/ui/settings/screen.py` exposes that configuration through the UI.

9. **Session and startup behavior**
   - `supernanno/services/session_manager.py` persists editor session metadata such as the last opened file.
   - On launch, startup flow can restore the previous file/session and optionally show the startup view (`ui/startup_view.py`) before or alongside editing.
   - This is a local persistence path, not a network-backed sync system.

10. **Observability and diagnostics**
   - Logging and error handling are first-class subsystems in `supernanno/services/log_service.py`, `error_service.py`, and `issue_service.py`.
   - Errors are classified, given correlation IDs, logged as structured events, and surfaced through the status bar.
   - The diagnostic flow can generate a GitHub issue report, but that is an explicit user action rather than automatic telemetry.

11. **State management**
   - `supernanno/states/base.py` and the specialized state modules capture app-level workflow state that should outlive a single widget callback.
   - This keeps transient UI state, search state, and editor/session state separated so Textual widgets remain relatively thin.

12. **External technology boundaries**
   - The app is a Python terminal application built on **Textual** and uses **Tree-sitter** for syntax parsing/highlighting, with **Pygments** as fallback for unsupported languages.
   - It is primarily offline/local-first; the only notable external integration is optional GitHub issue formatting through the diagnostic service.
   - Tests in `supernanno/tests/` focus on core/services behavior rather than depending heavily on the widget tree, reinforcing the separation between presentation and logic.

Main entry points: [`supernanno/app.py`](https://github.com/hbisneto/supernanno/blob/main/supernanno/app.py) (App), [`supernanno/ui/layout.py`](https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/layout.py) (Layout), [`supernanno/handlers`](https://github.com/hbisneto/supernanno/tree/main/supernanno/handlers) (Action handlers), [`supernanno/services/app_context.py`](https://github.com/hbisneto/supernanno/blob/main/supernanno/services/app_context.py) (App context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_entry["Entry & CLI"]
  node_n_main(("Startup<br/>entrypoint<br/>[__main__.py]"))
  node_n_app["App<br/>runtime shell<br/>[app.py]"]
  node_n_cli["CLI parser<br/>arg parsing<br/>[parser.py]"]
end

subgraph group_grp_ui["UI layer"]
  node_n_ui_layout["Layout<br/>[layout.py]"]
  node_n_ui_search["Search bar<br/>tui widget<br/>[search_bar.py]"]
  node_n_ui_startup["Startup view<br/>tui view<br/>[startup_view.py]"]
  node_n_ui_settings["Settings screen<br/>tui screen<br/>[screen.py]"]
  node_n_ui_bindings["Bindings<br/>shortcuts<br/>[bindings.py]"]
end

subgraph group_grp_events["Events"]
  node_n_events{{"UI events<br/>event models"}}
end

subgraph group_grp_handlers["Handlers"]
  node_n_handlers["Action handlers<br/>routing"]
end

subgraph group_grp_services["Services"]
  node_n_context[("App context<br/>façade<br/>[app_context.py]")]
  node_n_config["Config stack<br/>configuration<br/>[config_manager.py]"]
  node_n_session["Session manager<br/>persistence<br/>[session_manager.py]"]
  node_n_diagnostics["Diagnostics<br/>observability<br/>[error_service.py]"]
end

subgraph group_grp_core["Core"]
  node_n_editor["Editor core<br/>editing engine<br/>[editor.py]"]
  node_n_files[("File manager<br/>file I/O<br/>[file_manager.py]")]
  node_n_obs["Status logs<br/>feedback<br/>[status.py]"]
end

subgraph group_grp_search["Search"]
  node_n_search_ctrl["Search ctrl<br/>orchestration<br/>[controller.py]"]
  node_n_search_engine["Search engine<br/>matching<br/>[engine.py]"]
  node_n_search_modes{{"Search modes<br/>strategy registry<br/>[registry.py]"}}
end

subgraph group_grp_state["State"]
  node_n_search_state["Search state<br/>workflow state<br/>[search.py]"]
  node_n_app_state["App state<br/>shared state<br/>[base.py]"]
end

node_n_main -->|"parse args"| node_n_cli
node_n_main -->|"launch"| node_n_app
node_n_cli -->|"startup config"| node_n_app
node_n_app -->|"build context"| node_n_context
node_n_context -->|"load config"| node_n_config
node_n_context -->|"restore session"| node_n_session
node_n_context -->|"diagnose"| node_n_diagnostics
node_n_app -->|"mount UI"| node_n_ui_layout
node_n_app -->|"startup view"| node_n_ui_startup
node_n_app -->|"settings"| node_n_ui_settings
node_n_ui_layout -->|"contains"| node_n_ui_search
node_n_ui_layout -->|"shortcuts"| node_n_ui_bindings
node_n_ui_layout -->|"emit events"| node_n_events
node_n_ui_search -->|"submit input"| node_n_events
node_n_ui_startup -->|"select file"| node_n_events
node_n_events -->|"dispatch"| node_n_handlers
node_n_handlers -->|"edit flow"| node_n_editor
node_n_handlers -->|"file flow"| node_n_files
node_n_handlers -->|"search flow"| node_n_search_ctrl
node_n_editor -->|"persist"| node_n_files
node_n_editor -->|"status"| node_n_obs
node_n_diagnostics -->|"surface errors"| node_n_obs
node_n_search_ctrl -->|"choose mode"| node_n_search_modes
node_n_search_ctrl -->|"run query"| node_n_search_engine
node_n_search_ctrl -->|"track results"| node_n_search_state
node_n_search_engine -->|"update state"| node_n_search_state
node_n_app -->|"shared state"| node_n_app_state

click node_n_main "https://github.com/hbisneto/supernanno/blob/main/supernanno/__main__.py"
click node_n_app "https://github.com/hbisneto/supernanno/blob/main/supernanno/app.py"
click node_n_cli "https://github.com/hbisneto/supernanno/blob/main/supernanno/cli/parser.py"
click node_n_ui_layout "https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/layout.py"
click node_n_ui_search "https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/search_bar.py"
click node_n_ui_startup "https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/startup_view.py"
click node_n_ui_settings "https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/settings/screen.py"
click node_n_ui_bindings "https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/bindings.py"
click node_n_events "https://github.com/hbisneto/supernanno/tree/main/supernanno/events"
click node_n_handlers "https://github.com/hbisneto/supernanno/tree/main/supernanno/handlers"
click node_n_context "https://github.com/hbisneto/supernanno/blob/main/supernanno/services/app_context.py"
click node_n_config "https://github.com/hbisneto/supernanno/blob/main/supernanno/services/config_manager.py"
click node_n_session "https://github.com/hbisneto/supernanno/blob/main/supernanno/services/session_manager.py"
click node_n_diagnostics "https://github.com/hbisneto/supernanno/blob/main/supernanno/services/error_service.py"
click node_n_editor "https://github.com/hbisneto/supernanno/blob/main/supernanno/core/editor.py"
click node_n_files "https://github.com/hbisneto/supernanno/blob/main/supernanno/core/file_manager.py"
click node_n_obs "https://github.com/hbisneto/supernanno/blob/main/supernanno/core/status.py"
click node_n_search_ctrl "https://github.com/hbisneto/supernanno/blob/main/supernanno/search/controller.py"
click node_n_search_engine "https://github.com/hbisneto/supernanno/blob/main/supernanno/search/engine.py"
click node_n_search_modes "https://github.com/hbisneto/supernanno/blob/main/supernanno/search/registry.py"
click node_n_search_state "https://github.com/hbisneto/supernanno/blob/main/supernanno/states/search.py"
click node_n_app_state "https://github.com/hbisneto/supernanno/blob/main/supernanno/states/base.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_n_main,node_n_app,node_n_cli,node_n_search_ctrl,node_n_search_engine,node_n_search_modes toneBlue
class node_n_ui_layout,node_n_ui_search,node_n_ui_startup,node_n_ui_settings,node_n_ui_bindings,node_n_search_state,node_n_app_state toneAmber
class node_n_events toneMint
class node_n_handlers toneRose
class node_n_context,node_n_config,node_n_session,node_n_diagnostics toneIndigo
class node_n_editor,node_n_files,node_n_obs toneTeal
```

## Components

### Entry & CLI

Process startup and argument parsing

- [Startup](https://github.com/hbisneto/supernanno/blob/main/supernanno/__main__.py): entrypoint · Launches the Textual app · `supernanno/__main__.py`
- [App](https://github.com/hbisneto/supernanno/blob/main/supernanno/app.py): runtime shell · Bootstraps the application and wires subsystems · `supernanno/app.py`
- [CLI parser](https://github.com/hbisneto/supernanno/blob/main/supernanno/cli/parser.py): arg parsing · Parses file, mode, and startup options · `supernanno/cli/parser.py`

### UI layer

Textual widgets, layouts, bindings, and screens

- [Layout](https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/layout.py): tui layout · Main editor arrangement and screen composition · `supernanno/ui/layout.py`
- [Search bar](https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/search_bar.py): tui widget · Search input and query controls · `supernanno/ui/search_bar.py`
- [Startup view](https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/startup_view.py): tui view · Initial landing and file selection view · `supernanno/ui/startup_view.py`
- [Settings screen](https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/settings/screen.py): tui screen · Configuration editing interface · `supernanno/ui/settings/screen.py`
- [Bindings](https://github.com/hbisneto/supernanno/blob/main/supernanno/ui/bindings.py): shortcuts · Keyboard shortcut definitions · `supernanno/ui/bindings.py`

### Events

UI-generated interaction events

- [UI events](https://github.com/hbisneto/supernanno/tree/main/supernanno/events): event models · Key, input, mount, and selection events · `supernanno/events`

### Handlers

High-level action routing

- [Action handlers](https://github.com/hbisneto/supernanno/tree/main/supernanno/handlers): routing · File, quit, and sidebar actions · `supernanno/handlers`

### Services

Cross-cutting app services and configuration

- [App context](https://github.com/hbisneto/supernanno/blob/main/supernanno/services/app_context.py): façade · Shared access to config, logging, errors, session, and I/O · `supernanno/services/app_context.py`
- [Config stack](https://github.com/hbisneto/supernanno/blob/main/supernanno/services/config_manager.py): configuration · RC parsing, config merging, path resolution, and application · `supernanno/services/config_manager.py`
- [Session manager](https://github.com/hbisneto/supernanno/blob/main/supernanno/services/session_manager.py): persistence · Persists local session metadata such as last file · `supernanno/services/session_manager.py`
- [Diagnostics](https://github.com/hbisneto/supernanno/blob/main/supernanno/services/error_service.py): observability · Logging, structured errors, and issue reporting · `supernanno/services/error_service.py`

### Core

Editing, file I/O, and observability primitives

- [Editor core](https://github.com/hbisneto/supernanno/blob/main/supernanno/core/editor.py): editing engine · Editing state and buffer operations · `supernanno/core/editor.py`
- [File manager](https://github.com/hbisneto/supernanno/blob/main/supernanno/core/file_manager.py): file I/O · Atomic saves, backups, and file access · `supernanno/core/file_manager.py`
- [Status logs](https://github.com/hbisneto/supernanno/blob/main/supernanno/core/status.py): feedback · Status messaging and structured logging support · `supernanno/core/status.py`

### Search

Search strategies and coordination

- [Search ctrl](https://github.com/hbisneto/supernanno/blob/main/supernanno/search/controller.py): orchestration · Coordinates search actions and search state · `supernanno/search/controller.py`
- [Search engine](https://github.com/hbisneto/supernanno/blob/main/supernanno/search/engine.py): matching · Executes query matching against content · `supernanno/search/engine.py`
- [Search modes](https://github.com/hbisneto/supernanno/blob/main/supernanno/search/registry.py): strategy registry · Selects literal, case-sensitive, and regex strategies · `supernanno/search/registry.py`

### State

App and search state models

- [Search state](https://github.com/hbisneto/supernanno/blob/main/supernanno/states/search.py): workflow state · Tracks search mode, query, and results · `supernanno/states/search.py`
- [App state](https://github.com/hbisneto/supernanno/blob/main/supernanno/states/base.py): shared state · General workflow state shared across widgets · `supernanno/states/base.py`

## Connections

- Startup → CLI parser: parse args · Startup reads command-line options before UI mount
- Startup → App: launch · Entrypoint starts the application runtime
- CLI parser → App: startup config · CLI decisions feed app initialization
- App → App context: build context · App creates the shared boundary object
- App context → Config stack: load config · Context exposes configuration services
- App context → Session manager: restore session · Context provides persisted session data
- App context → Diagnostics: diagnose · Context centralizes logging and error handling
- App → Layout: mount UI · App composes the main Textual layout
- App → Startup view: startup view · Initial screen can be shown on launch
- App → Settings screen: settings · Settings screen is part of the UI surface
- Layout → Search bar: contains · Layout includes the search interface
- Layout → Bindings: shortcuts · Layout uses centralized key bindings
- Layout → UI events: emit events · Widgets translate input into events
- Search bar → UI events: submit input · Search input emits interaction events
- Startup view → UI events: select file · Startup interactions become events
- UI events → Action handlers: dispatch · Events are handled by action modules
- Action handlers → Editor core: edit flow · Handlers coordinate editor actions
- Action handlers → File manager: file flow · Handlers delegate file operations to file manager
- Action handlers → Search ctrl: search flow · Handlers invoke search orchestration
- Editor core → File manager: persist · Editor uses file I/O for loading and saving
- Editor core → Status logs: status · Editor reports progress and issues
- Diagnostics → Status logs: surface errors · Diagnostics feed structured status and logs
- Search ctrl → Search modes: choose mode · Controller selects the runtime search strategy
- Search ctrl → Search engine: run query · Controller delegates matching work to the engine
- Search ctrl → Search state: track results · Search workflow state is maintained separately
- Search engine → Search state: update state · Matches and mode changes are reflected in state
- App → App state: shared state · Application workflow state is stored centrally