# akshatjski/p2p-terminal-chat architecture

> Architecture diagram of the GitHub repository akshatjski/p2p-terminal-chat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akshatjski/p2p-terminal-chat
- Repository: https://github.com/akshatjski/p2p-terminal-chat

## Overview

P2P Terminal Chat is a terminal-based, end-to-end encrypted peer-to-peer chat application. A host announces and accepts connections; a joiner discovers or enters a host address, verifies its fingerprint, and joins a room to exchange messages. Host-side room relaying also supports moderation, history, file transfer, games, and bridging rooms across networks; mesh mode provides a separate multi-hop relay path. The graph reflects README capabilities where source excerpts are incomplete, so some subsystem wiring is intentionally not inferred.

Main entry points: [`src/main/java/com/p2p/chat/ClientMain.java`](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/ClientMain.java) (CLI entry), [`src/main/java/com/p2p/chat/core/HostNode.java`](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/HostNode.java) (Host node), [`src/main/java/com/p2p/chat/core/ClientNode.java`](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/ClientNode.java) (Client node), [`src/main/java/com/p2p/chat/crypto/SecureChannel.java`](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/SecureChannel.java) (Secure channel)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Terminal app"]
  node_main["CLI entry<br/>[ClientMain.java]"]
  node_config["Configuration<br/>[Config.java]"]
end

subgraph group_network["Peer connectivity"]
  node_discovery["LAN discovery<br/>[Discovery.java]"]
  node_announcer["Presence announcer"]
  node_scanner["Host scanner"]
  node_joinpicker["Join selection<br/>[JoinPicker.java]"]
  node_tailscale["Tailnet status"]
  node_reconnect["Reconnect channel"]
  node_transport["Socket transport"]
end

subgraph group_security["Secure channels"]
  node_identity["Peer identity<br/>[Identity.java]"]
  node_secure["Secure channel<br/>[SecureChannel.java]"]
  node_cryptoutil["Crypto primitives<br/>[CryptoUtil.java]"]
  node_trustgate["Trust verification<br/>[TrustGate.java]"]
  node_truststore[("Trusted peers<br/>[TrustStore.java]")]
end

subgraph group_rooms["Room features"]
  node_host["Host node<br/>[HostNode.java]"]
  node_client["Client node<br/>[ClientNode.java]"]
  node_protocol["Chat protocol<br/>[Protocol.java]"]
  node_history[("Message history")]
  node_files["File receiving<br/>[FileReceiver.java]"]
  node_games["Room games<br/>[GameEngine.java]"]
  node_hints["Dynamic game hints"]
  node_bridge["Host room bridge<br/>[HostNode.java]"]
end

subgraph group_mesh["Mesh mode"]
  node_meshmain["Mesh entry<br/>[MeshMain.java]"]
  node_meshnode["Mesh relay node<br/>[MeshNode.java]"]
  node_meshlink["Mesh link<br/>[MeshLink.java]"]
end

node_user(("Terminal user"))
node_tailnet(("Tailscale CLI"))
node_remotepeer(("Remote peer"))
node_multicast(("LAN multicast"))
node_itunes(("iTunes services"))

node_user -->|"starts chat"| node_main
node_main -->|"loads settings"| node_config
node_main -->|"loads identity"| node_identity
node_main -->|"starts host"| node_host
node_main -->|"joins host"| node_client
node_main -->|"announces presence"| node_announcer
node_main -->|"scans hosts"| node_scanner
node_main -->|"checks tailnet"| node_tailscale
node_announcer -->|"broadcasts presence"| node_multicast
node_scanner -->|"scans presence"| node_multicast
node_scanner -->|"parses records"| node_discovery
node_main -->|"selects host"| node_joinpicker
node_tailscale -->|"queries status"| node_tailnet
node_client -->|"connects to host"| node_remotepeer
node_client -->|"recovers connection"| node_reconnect
node_reconnect -->|"re-establishes channel"| node_secure
node_host -->|"secures connections"| node_secure
node_client -->|"secures connection"| node_secure
node_secure -->|"encrypts messages"| node_cryptoutil
node_secure -->|"uses key identity"| node_identity
node_host -->|"verifies peers"| node_trustgate
node_client -->|"verifies host"| node_trustgate
node_trustgate -->|"checks fingerprints"| node_truststore
node_client -->|"sends protocol data"| node_transport
node_host -->|"sends protocol data"| node_transport
node_client -->|"formats room commands"| node_protocol
node_host -->|"routes room commands"| node_protocol
node_host -->|"records messages"| node_history
node_client -->|"receives file chunks"| node_files
node_host -->|"routes game commands"| node_games
node_games -.->|"requests clues"| node_hints
node_hints -.->|"fetches chart data"| node_itunes
node_host -->|"bridges host rooms"| node_bridge
node_user -->|"starts mesh mode"| node_meshmain
node_meshmain -->|"starts relay node"| node_meshnode
node_meshnode -->|"manages peer links"| node_meshlink
node_meshnode -->|"secures peer links"| node_secure
node_meshnode -->|"verifies peers"| node_trustgate
node_meshnode -->|"relays mesh messages"| node_protocol

click node_main "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/ClientMain.java"
click node_config "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/config/Config.java"
click node_host "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/HostNode.java"
click node_client "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/ClientNode.java"
click node_discovery "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/Discovery.java"
click node_announcer "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/DiscoveryAnnouncer.java"
click node_scanner "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/DiscoveryScanner.java"
click node_joinpicker "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/JoinPicker.java"
click node_tailscale "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/TailscaleStatus.java"
click node_identity "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/Identity.java"
click node_secure "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/SecureChannel.java"
click node_cryptoutil "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/CryptoUtil.java"
click node_trustgate "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/TrustGate.java"
click node_truststore "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/TrustStore.java"
click node_protocol "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/protocol/Protocol.java"
click node_history "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/MessageHistory.java"
click node_files "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/FileReceiver.java"
click node_games "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/game/GameEngine.java"
click node_hints "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/game/guess/ItunesHintSource.java"
click node_bridge "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/HostNode.java"
click node_reconnect "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/ReconnectableChannel.java"
click node_transport "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/transport/SocketTransport.java"
click node_meshmain "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/mesh/MeshMain.java"
click node_meshnode "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/mesh/MeshNode.java"
click node_meshlink "https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/mesh/MeshLink.java"

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_main,node_config,node_user toneBlue
class node_discovery,node_announcer,node_scanner,node_joinpicker,node_tailscale,node_reconnect,node_transport toneAmber
class node_identity,node_secure,node_cryptoutil,node_trustgate,node_truststore toneMint
class node_host,node_client,node_protocol,node_history,node_files,node_games,node_hints,node_bridge toneRose
class node_meshmain,node_meshnode,node_meshlink,node_tailnet,node_remotepeer,node_multicast,node_itunes toneIndigo
```

## Components

### Terminal app

- [CLI entry](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/ClientMain.java): `src/main/java/com/p2p/chat/ClientMain.java`
- [Configuration](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/config/Config.java): `src/main/java/com/p2p/chat/config/Config.java`

### Peer connectivity

- [LAN discovery](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/Discovery.java): `src/main/java/com/p2p/chat/discovery/Discovery.java`
- [Presence announcer](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/DiscoveryAnnouncer.java): `src/main/java/com/p2p/chat/discovery/DiscoveryAnnouncer.java`
- [Host scanner](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/DiscoveryScanner.java): `src/main/java/com/p2p/chat/discovery/DiscoveryScanner.java`
- [Join selection](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/JoinPicker.java): `src/main/java/com/p2p/chat/discovery/JoinPicker.java`
- [Tailnet status](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/discovery/TailscaleStatus.java): `src/main/java/com/p2p/chat/discovery/TailscaleStatus.java`
- [Reconnect channel](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/ReconnectableChannel.java): `src/main/java/com/p2p/chat/core/ReconnectableChannel.java`
- [Socket transport](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/transport/SocketTransport.java): `src/main/java/com/p2p/chat/transport/SocketTransport.java`

### Secure channels

- [Peer identity](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/Identity.java): `src/main/java/com/p2p/chat/crypto/Identity.java`
- [Secure channel](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/SecureChannel.java): `src/main/java/com/p2p/chat/crypto/SecureChannel.java`
- [Crypto primitives](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/CryptoUtil.java): `src/main/java/com/p2p/chat/crypto/CryptoUtil.java`
- [Trust verification](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/TrustGate.java): `src/main/java/com/p2p/chat/core/TrustGate.java`
- [Trusted peers](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/crypto/TrustStore.java): `src/main/java/com/p2p/chat/crypto/TrustStore.java`

### Room features

- [Host node](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/HostNode.java): `src/main/java/com/p2p/chat/core/HostNode.java`
- [Client node](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/ClientNode.java): `src/main/java/com/p2p/chat/core/ClientNode.java`
- [Chat protocol](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/protocol/Protocol.java): `src/main/java/com/p2p/chat/protocol/Protocol.java`
- [Message history](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/MessageHistory.java): `src/main/java/com/p2p/chat/core/MessageHistory.java`
- [File receiving](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/FileReceiver.java): `src/main/java/com/p2p/chat/core/FileReceiver.java`
- [Room games](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/game/GameEngine.java): `src/main/java/com/p2p/chat/game/GameEngine.java`
- [Dynamic game hints](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/game/guess/ItunesHintSource.java): `src/main/java/com/p2p/chat/game/guess/ItunesHintSource.java`
- [Host room bridge](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/core/HostNode.java): `src/main/java/com/p2p/chat/core/HostNode.java`

### Mesh mode

- [Mesh entry](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/mesh/MeshMain.java): `src/main/java/com/p2p/chat/mesh/MeshMain.java`
- [Mesh relay node](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/mesh/MeshNode.java): `src/main/java/com/p2p/chat/mesh/MeshNode.java`
- [Mesh link](https://github.com/akshatjski/p2p-terminal-chat/blob/main/src/main/java/com/p2p/chat/mesh/MeshLink.java): `src/main/java/com/p2p/chat/mesh/MeshLink.java`

### Other components

- **Terminal user**
- **Tailscale CLI**
- **Remote peer**
- **LAN multicast**
- **iTunes services**

## Connections

- Terminal user → CLI entry: starts chat
- CLI entry → Configuration: loads settings
- CLI entry → Peer identity: loads identity
- CLI entry → Host node: starts host
- CLI entry → Client node: joins host
- CLI entry → Presence announcer: announces presence
- CLI entry → Host scanner: scans hosts
- CLI entry → Tailnet status: checks tailnet
- Presence announcer → LAN multicast: broadcasts presence
- Host scanner → LAN multicast: scans presence
- Host scanner → LAN discovery: parses records
- CLI entry → Join selection: selects host
- Tailnet status → Tailscale CLI: queries status
- Client node → Remote peer: connects to host
- Client node → Reconnect channel: recovers connection
- Reconnect channel → Secure channel: re-establishes channel
- Host node → Secure channel: secures connections
- Client node → Secure channel: secures connection
- Secure channel → Crypto primitives: encrypts messages
- Secure channel → Peer identity: uses key identity
- Host node → Trust verification: verifies peers
- Client node → Trust verification: verifies host
- Trust verification → Trusted peers: checks fingerprints
- Client node → Socket transport: sends protocol data
- Host node → Socket transport: sends protocol data
- Client node → Chat protocol: formats room commands
- Host node → Chat protocol: routes room commands
- Host node → Message history: records messages
- Client node → File receiving: receives file chunks
- Host node → Room games: routes game commands
- Room games → Dynamic game hints: requests clues
- Dynamic game hints → iTunes services: fetches chart data
- Host node → Host room bridge: bridges host rooms
- Terminal user → Mesh entry: starts mesh mode
- Mesh entry → Mesh relay node: starts relay node
- Mesh relay node → Mesh link: manages peer links
- Mesh relay node → Secure channel: secures peer links
- Mesh relay node → Trust verification: verifies peers
- Mesh relay node → Chat protocol: relays mesh messages