# alhanshim/socketchat architecture

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

- Interactive diagram: https://gitdiagram.com/alhanshim/socketchat
- Repository: https://github.com/alhanshim/socketchat

## Overview

SocketChat is a terminal LAN messenger: users choose automatic discovery or enter a peer IP, establish a connection, and exchange per-chat encrypted messages. A background listener can notify the user of incoming connection requests, which they may accept or ignore. The graph separates the UI and orchestration, discovery and connection stages, and chat transport/security. Some implementation details are unsampled; edges rely on the README or the cited excerpts and SOURCE INDEX references.

Main entry points: [`socketchat/window.py`](https://github.com/alhanshim/socketchat/blob/main/socketchat/window.py) (App coordinator), [`socketchat/tui/welcome_page.py`](https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/welcome_page.py) (Welcome screen), [`socketchat/functions.py`](https://github.com/alhanshim/socketchat/blob/main/socketchat/functions.py) (Socket transport), [`socketchat/startup.py`](https://github.com/alhanshim/socketchat/blob/main/socketchat/startup.py) (Discovery protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Terminal interface"]
  node_cli["CLI entry<br/>[commands.py]"]
  node_welcome["Welcome screen<br/>[welcome_page.py]"]
  node_auto_ui["Auto-connect screen<br/>[auto_loading.py]"]
  node_ip_ui["IP-connect screen<br/>[ip_loading.py]"]
  node_loading["Loading indicator<br/>[loading.py]"]
  node_chat_ui["Chat screen<br/>[chat.py]"]
end

subgraph group_coord["Session coordination"]
  node_app["App coordinator<br/>[window.py]"]
  node_parser["Command parser<br/>[core.py]"]
end

subgraph group_connect["LAN connection"]
  node_listener["Background listener<br/>[core.py]"]
  node_discovery["Discovery protocol<br/>[startup.py]"]
  node_direct["Direct connector<br/>[connecting.py]"]
end

subgraph group_messaging["Chat transport"]
  node_transport["Socket transport<br/>[functions.py]"]
  node_crypto["Message encryption<br/>[functions.py]"]
end

node_user(("User"))
node_peer(("LAN peer"))

node_user -->|"starts"| node_cli
node_cli -->|"runs"| node_app
node_app -->|"shows"| node_welcome
node_user -->|"chooses mode"| node_welcome
node_welcome -->|"parses command"| node_parser
node_welcome -->|"opens auto mode"| node_auto_ui
node_welcome -->|"opens IP mode"| node_ip_ui
node_app -->|"starts listener"| node_listener
node_listener -->|"runs listener"| node_discovery
node_discovery -->|"broadcasts packets"| node_peer
node_peer -->|"replies by UDP"| node_discovery
node_auto_ui -->|"starts discovery"| node_discovery
node_auto_ui -->|"opens chat"| node_app
node_ip_ui -->|"renders"| node_loading
node_ip_ui -->|"starts connection"| node_direct
node_direct -->|"sends unicast"| node_discovery
node_direct -->|"starts server"| node_app
node_peer -->|"connects by TCP"| node_direct
node_ip_ui -->|"opens on connect"| node_chat_ui
node_app -->|"starts socket route"| node_transport
node_chat_ui -->|"queues messages"| node_transport
node_transport -->|"encrypts messages"| node_crypto
node_transport -->|"delivers received text"| node_chat_ui
node_peer -->|"exchanges messages"| node_transport

click node_cli "https://github.com/alhanshim/socketchat/blob/main/socketchat/commands.py"
click node_app "https://github.com/alhanshim/socketchat/blob/main/socketchat/window.py"
click node_welcome "https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/welcome_page.py"
click node_parser "https://github.com/alhanshim/socketchat/blob/main/socketchat/core.py"
click node_auto_ui "https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/auto_loading.py"
click node_ip_ui "https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/ip_loading.py"
click node_loading "https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/loading.py"
click node_chat_ui "https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/chat.py"
click node_listener "https://github.com/alhanshim/socketchat/blob/main/socketchat/core.py"
click node_discovery "https://github.com/alhanshim/socketchat/blob/main/socketchat/startup.py"
click node_direct "https://github.com/alhanshim/socketchat/blob/main/socketchat/connecting.py"
click node_transport "https://github.com/alhanshim/socketchat/blob/main/socketchat/functions.py"
click node_crypto "https://github.com/alhanshim/socketchat/blob/main/socketchat/functions.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_welcome,node_auto_ui,node_ip_ui,node_loading,node_chat_ui,node_user toneBlue
class node_app,node_parser toneAmber
class node_listener,node_discovery,node_direct toneMint
class node_transport,node_crypto toneRose
class node_peer toneIndigo
```

## Components

### Terminal interface

- [CLI entry](https://github.com/alhanshim/socketchat/blob/main/socketchat/commands.py): `socketchat/commands.py`
- [Welcome screen](https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/welcome_page.py): `socketchat/tui/welcome_page.py`
- [Auto-connect screen](https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/auto_loading.py): `socketchat/tui/auto_loading.py`
- [IP-connect screen](https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/ip_loading.py): `socketchat/tui/ip_loading.py`
- [Loading indicator](https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/loading.py): `socketchat/tui/loading.py`
- [Chat screen](https://github.com/alhanshim/socketchat/blob/main/socketchat/tui/chat.py): `socketchat/tui/chat.py`

### Session coordination

- [App coordinator](https://github.com/alhanshim/socketchat/blob/main/socketchat/window.py): `socketchat/window.py`
- [Command parser](https://github.com/alhanshim/socketchat/blob/main/socketchat/core.py): `socketchat/core.py`

### LAN connection

- [Background listener](https://github.com/alhanshim/socketchat/blob/main/socketchat/core.py): `socketchat/core.py`
- [Discovery protocol](https://github.com/alhanshim/socketchat/blob/main/socketchat/startup.py): `socketchat/startup.py`
- [Direct connector](https://github.com/alhanshim/socketchat/blob/main/socketchat/connecting.py): `socketchat/connecting.py`

### Chat transport

- [Socket transport](https://github.com/alhanshim/socketchat/blob/main/socketchat/functions.py): `socketchat/functions.py`
- [Message encryption](https://github.com/alhanshim/socketchat/blob/main/socketchat/functions.py): `socketchat/functions.py`

### Other components

- **User**
- **LAN peer**

## Connections

- User → CLI entry: starts (evidence: `README.md`)
- CLI entry → App coordinator: runs (evidence: `socketchat/commands.py`)
- App coordinator → Welcome screen: shows (evidence: `socketchat/window.py`)
- User → Welcome screen: chooses mode (evidence: `README.md`)
- Welcome screen → Command parser: parses command (evidence: `socketchat/tui/welcome_page.py`)
- Welcome screen → Auto-connect screen: opens auto mode (evidence: `socketchat/tui/welcome_page.py`)
- Welcome screen → IP-connect screen: opens IP mode (evidence: `socketchat/tui/welcome_page.py`)
- App coordinator → Background listener: starts listener (evidence: `socketchat/window.py`)
- Background listener → Discovery protocol: runs listener (evidence: `socketchat/core.py`)
- Discovery protocol → LAN peer: broadcasts packets (evidence: `README.md`)
- LAN peer → Discovery protocol: replies by UDP (evidence: `README.md`)
- Auto-connect screen → Discovery protocol: starts discovery (evidence: `socketchat/tui/auto_loading.py`)
- Auto-connect screen → App coordinator: opens chat (evidence: `socketchat/tui/auto_loading.py`)
- IP-connect screen → Loading indicator: renders (evidence: `socketchat/tui/ip_loading.py`)
- IP-connect screen → Direct connector: starts connection (evidence: `socketchat/tui/ip_loading.py`)
- Direct connector → Discovery protocol: sends unicast (evidence: `socketchat/connecting.py`)
- Direct connector → App coordinator: starts server (evidence: `socketchat/connecting.py`)
- LAN peer → Direct connector: connects by TCP (evidence: `README.md`)
- IP-connect screen → Chat screen: opens on connect (evidence: `socketchat/tui/ip_loading.py`)
- App coordinator → Socket transport: starts socket route (evidence: `socketchat/window.py`)
- Chat screen → Socket transport: queues messages (evidence: `socketchat/tui/chat.py`)
- Socket transport → Message encryption: encrypts messages (evidence: `README.md`)
- Socket transport → Chat screen: delivers received text (evidence: `socketchat/functions.py`)
- LAN peer → Socket transport: exchanges messages (evidence: `README.md`)
