# unight0/ssrpi architecture

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

- Interactive diagram: https://gitdiagram.com/unight0/ssrpi
- Repository: https://github.com/unight0/ssrpi

## Overview

#### Purpose and Executables
SSRPI is a Go client-server secure chatroom implementation. The server accepts TLS connections, authenticates users, maintains chatroom/admin state, and persists user data in SQLite. The client is an interactive terminal application for login, chat, administration, and file operations.

Entry points:
- Server process: `serv/main.go`
- Terminal client process: `client/main.go`
- Protocol contract: `PROTOCOL.md`

#### Protocol and Trust Boundary
`PROTOCOL.md` defines the application wire protocol shared by both independently built binaries. TLS protects transport confidentiality and integrity; protocol-level authentication then establishes user identity and authorization.

The public network boundary is the server listener in `serv/main.go`. Client input and remote server messages cross separate trust boundaries in `client/main.go`; server-side command handling must enforce authorization rather than trusting client UI behavior.

#### Server Runtime and State
`serv/main.go` is the authoritative service runtime. It is responsible for:
- Loading the TLS certificate/key and listening on the configured TCP port.
- Managing concurrent client sessions and message distribution.
- Registration, login, password changes, admin promotion/revocation, kicks, and shutdown.
- Enforcing the shared server password and per-user privileges.
- Loading and presenting an optional MOTD.

Persistent account state is backed by SQLite, configured through the server’s database-path flag. This requires CGO, as declared by the repository build requirements. TLS material is generated or provisioned outside the binary; `serv/makecert.sh` is the local certificate-generation entry point.

#### Client Interaction Layer
`client/main.go` owns connection setup and the Bubble Tea terminal UI. It obtains connection credentials from flags or interactive prompts, opens the TLS session, performs protocol authentication, and renders incoming chat/system events.

The client maps slash commands into protocol requests, including broadcast/direct chat, user listing, file upload/download, self-service password changes, and privileged administration. It should treat authorization failures and server-originated state as authoritative.

#### Messaging, Presence, and Administration Flow
The primary control flow is:
1. Client connects over TLS and provides server/user credentials.
2. Server validates the server password and user account state, registering users when applicable.
3. Server tracks the authenticated session and broadcasts presence/chat events to relevant connected clients.
4. Client submits user or admin commands; server validates identity and admin status before mutating shared state.
5. Session disconnect, kick, or shutdown removes/terminates active connections.

The first registered user becomes an administrator, making initial registration a bootstrap boundary. Administrative operations—including server-password changes and remote shutdown—are server-owned actions in `serv/main.go`, not client-enforced permissions.

#### File Transfer Boundary
The command surface includes upload and download operations, with recipient targeting for uploads. These operations are protocol-defined in `PROTOCOL.md`, initiated from `client/main.go`, and mediated by `serv/main.go`. The server is the coordination and authorization point for file identifiers, aliases, recipient selection, and retrieval; clients should not assume peer-to-peer transfer.

#### Build and Deployment Shape
The repository contains two separate Go modules:
- `serv/go.mod`
- `client/go.mod`

They are built and deployed as separate executables, enabling the server to run as the long-lived TLS/SQLite service while clients remain disposable terminal sessions. Required operational dependencies are Go 1.21+, CGO/SQLite support, a server certificate/key pair, and optionally an MOTD text file.

Main entry points: [`client/main.go`](https://github.com/unight0/ssrpi/blob/master/client/main.go) (Terminal client), [`serv/main.go`](https://github.com/unight0/ssrpi/blob/master/serv/main.go) (Authentication & admin), [`PROTOCOL.md`](https://github.com/unight0/ssrpi/blob/master/PROTOCOL.md) (Wire protocol), [`serv/makecert.sh`](https://github.com/unight0/ssrpi/blob/master/serv/makecert.sh) (Certificate & key)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_server["Server runtime"]
  node_server_main["Server process<br/>Go executable<br/>[main.go]"]
  node_server_tls["TLS listener<br/>network boundary<br/>[main.go]"]
  node_session_manager["Sessions &amp; distribution<br/>server state<br/>[main.go]"]
  node_auth_admin["Authentication &amp; admin<br/>authorization<br/>[main.go]"]
  node_file_mediator["File mediation<br/>transfer coordinator<br/>[main.go]"]
  node_sqlite[("Account database<br/>SQLite<br/>[main.go]")]
  node_tls_material["Certificate &amp; key<br/>TLS material<br/>[makecert.sh]"]
  node_motd["Optional MOTD<br/>text input<br/>[main.go]"]
  node_server_module["Server module<br/>Go module<br/>[go.mod]"]
end

subgraph group_client["Terminal client"]
  node_client_main["Terminal client<br/>Go executable<br/>[main.go]"]
  node_client_input["Prompts &amp; slash commands<br/>untrusted input<br/>[main.go]"]
  node_terminal_ui["Bubble Tea UI<br/>terminal UI<br/>[main.go]"]
  node_client_tls["TLS connection<br/>network client<br/>[main.go]"]
  node_client_module["Client module<br/>Go module<br/>[go.mod]"]
end

node_protocol["Wire protocol<br/>protocol contract<br/>[PROTOCOL.md]"]

node_client_module -->|"builds"| node_client_main
node_server_module -->|"builds"| node_server_main
node_client_input -->|"credentials and commands"| node_client_main
node_client_main -->|"opens"| node_client_tls
node_client_tls -->|"TLS session"| node_server_tls
node_protocol -.->|"implements"| node_client_main
node_protocol -.->|"implements"| node_server_main
node_tls_material -->|"secures"| node_server_tls
node_server_main -->|"hosts"| node_server_tls
node_server_tls -->|"authentication requests"| node_auth_admin
node_auth_admin -->|"loads and mutates accounts"| node_sqlite
node_auth_admin -->|"admits or terminates sessions"| node_session_manager
node_session_manager -->|"chat, presence, system events"| node_terminal_ui
node_client_main -->|"renders through"| node_terminal_ui
node_client_main -->|"user and admin requests"| node_auth_admin
node_auth_admin -->|"authorizes transfers"| node_file_mediator
node_client_main -->|"upload and download requests"| node_file_mediator
node_server_main -->|"loads"| node_motd

click node_protocol "https://github.com/unight0/ssrpi/blob/master/PROTOCOL.md"
click node_server_main "https://github.com/unight0/ssrpi/blob/master/serv/main.go"
click node_server_tls "https://github.com/unight0/ssrpi/blob/master/serv/main.go"
click node_session_manager "https://github.com/unight0/ssrpi/blob/master/serv/main.go"
click node_auth_admin "https://github.com/unight0/ssrpi/blob/master/serv/main.go"
click node_file_mediator "https://github.com/unight0/ssrpi/blob/master/serv/main.go"
click node_sqlite "https://github.com/unight0/ssrpi/blob/master/serv/main.go"
click node_tls_material "https://github.com/unight0/ssrpi/blob/master/serv/makecert.sh"
click node_motd "https://github.com/unight0/ssrpi/blob/master/serv/main.go"
click node_server_module "https://github.com/unight0/ssrpi/blob/master/serv/go.mod"
click node_client_main "https://github.com/unight0/ssrpi/blob/master/client/main.go"
click node_client_input "https://github.com/unight0/ssrpi/blob/master/client/main.go"
click node_terminal_ui "https://github.com/unight0/ssrpi/blob/master/client/main.go"
click node_client_tls "https://github.com/unight0/ssrpi/blob/master/client/main.go"
click node_client_module "https://github.com/unight0/ssrpi/blob/master/client/go.mod"

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_server_main,node_server_tls,node_session_manager,node_auth_admin,node_file_mediator,node_sqlite,node_tls_material,node_motd,node_server_module toneBlue
class node_client_main,node_client_input,node_terminal_ui,node_client_tls,node_client_module toneAmber
class node_protocol toneNeutral
```

## Components

### Server runtime

Long-lived authoritative chat service.

- [Server process](https://github.com/unight0/ssrpi/blob/master/serv/main.go): Go executable · TLS listener, session manager, and authorization authority. · `serv/main.go`
- [TLS listener](https://github.com/unight0/ssrpi/blob/master/serv/main.go): network boundary · Accepts protected client TCP connections. · `serv/main.go`
- [Sessions & distribution](https://github.com/unight0/ssrpi/blob/master/serv/main.go): server state · Tracks authenticated clients and broadcasts events. · `serv/main.go`
- [Authentication & admin](https://github.com/unight0/ssrpi/blob/master/serv/main.go): authorization · Validates credentials, privileges, kicks, and shutdown. · `serv/main.go`
- [File mediation](https://github.com/unight0/ssrpi/blob/master/serv/main.go): transfer coordinator · Authorizes uploads, recipients, aliases, and retrieval. · `serv/main.go`
- [Account database](https://github.com/unight0/ssrpi/blob/master/serv/main.go): SQLite · Persistent user and account state. · `serv/main.go`
- [Certificate & key](https://github.com/unight0/ssrpi/blob/master/serv/makecert.sh): TLS material · Provisioned outside the server binary. · `serv/makecert.sh`
- [Optional MOTD](https://github.com/unight0/ssrpi/blob/master/serv/main.go): text input · Loaded and presented by the server. · `serv/main.go`
- [Server module](https://github.com/unight0/ssrpi/blob/master/serv/go.mod): Go module · Requires CGO-backed SQLite support. · `serv/go.mod`

### Terminal client

Interactive disposable client session.

- [Terminal client](https://github.com/unight0/ssrpi/blob/master/client/main.go): Go executable · Connects, authenticates, and renders chat/system events. · `client/main.go`
- [Prompts & slash commands](https://github.com/unight0/ssrpi/blob/master/client/main.go): untrusted input · Maps user actions to protocol requests. · `client/main.go`
- [Bubble Tea UI](https://github.com/unight0/ssrpi/blob/master/client/main.go): terminal UI · Displays incoming chat, presence, and server state. · `client/main.go`
- [TLS connection](https://github.com/unight0/ssrpi/blob/master/client/main.go): network client · Establishes the protected server session. · `client/main.go`
- [Client module](https://github.com/unight0/ssrpi/blob/master/client/go.mod): Go module · `client/go.mod`

### Other components

- [Wire protocol](https://github.com/unight0/ssrpi/blob/master/PROTOCOL.md): protocol contract · Shared contract for authentication, chat, administration, and files. · `PROTOCOL.md`

## Connections

- Client module → Terminal client: builds
- Server module → Server process: builds
- Prompts & slash commands → Terminal client: credentials and commands
- Terminal client → TLS connection: opens
- TLS connection → TLS listener: TLS session
- Wire protocol → Terminal client: implements
- Wire protocol → Server process: implements
- Certificate & key → TLS listener: secures
- Server process → TLS listener: hosts
- TLS listener → Authentication & admin: authentication requests
- Authentication & admin → Account database: loads and mutates accounts
- Authentication & admin → Sessions & distribution: admits or terminates sessions
- Sessions & distribution → Bubble Tea UI: chat, presence, system events
- Terminal client → Bubble Tea UI: renders through
- Terminal client → Authentication & admin: user and admin requests
- Authentication & admin → File mediation: authorizes transfers
- Terminal client → File mediation: upload and download requests
- Server process → Optional MOTD: loads