# shonix/chitchatserver architecture

> Architecture diagram of the GitHub repository shonix/chitchatserver, 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/shonix/chitchatserver
- Repository: https://github.com/shonix/chitchatserver

## Overview

ChitChat is a distributed terminal chat service. A user joins with a username, sends messages through a bidirectional gRPC stream, and receives broadcasts from other participants. The server registers streams, validates messages, updates Lamport timestamps, and broadcasts join, chat, and leave events; clients update their own clocks and display received messages. The protobuf contract defines the streamed message and RPC. Logging and graceful server shutdown are supporting runtime capabilities. The README documents these features; links below reflect the sampled client and server code.

Main entry points: [`server/server.go`](https://github.com/shonix/chitchatserver/blob/master/server/server.go) (Chat stream handler), [`client/client.go`](https://github.com/shonix/chitchatserver/blob/master/client/client.go) (Client send and display), [`grpc/proto_grpc.pb.go`](https://github.com/shonix/chitchatserver/blob/master/grpc/proto_grpc.pb.go) (Generated server dispatch), [`grpc/proto.proto`](https://github.com/shonix/chitchatserver/blob/master/grpc/proto.proto) (Stream message contract)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Terminal clients"]
  node_client["Client entry<br/>[client.go]"]
  node_input["Input and validation<br/>[client.go]"]
  node_clientclock["Client Lamport clock<br/>[client.go]"]
  node_clientio["Client send and display<br/>[client.go]"]
  node_clientlogging["Client logging<br/>[client.go]"]
end

subgraph group_service["Chat service"]
  node_servermain["Server entry<br/>[server.go]"]
  node_chat["Chat stream handler<br/>[server.go]"]
  node_serverclock["Server Lamport clock<br/>[server.go]"]
  node_registry["Client stream registry<br/>[server.go]"]
  node_broadcast["Event broadcast<br/>[server.go]"]
  node_logging["Structured logging<br/>[server.go]"]
end

subgraph group_transport["gRPC contract"]
  node_rpcclient["Generated client RPC<br/>[proto_grpc.pb.go]"]
  node_rpcserver["Generated server dispatch<br/>[proto_grpc.pb.go]"]
  node_contract["Stream message contract<br/>[proto.proto]"]
end

node_user(("Chat user"))

node_user -->|"starts client"| node_client
node_user -->|"enters messages"| node_input
node_client -->|"opens stream"| node_rpcclient
node_client -->|"starts receive loop"| node_clientio
node_input -->|"submits text"| node_clientio
node_clientio -->|"timestamps sends"| node_clientclock
node_clientio -->|"sends and receives"| node_rpcclient
node_input -->|"logs rejections"| node_clientlogging
node_clientio -->|"logs activity"| node_clientlogging
node_rpcclient -->|"encodes stream"| node_contract
node_contract -->|"defines stream"| node_rpcserver
node_servermain -->|"registers handler"| node_rpcserver
node_servermain -->|"logs lifecycle"| node_logging
node_rpcserver -->|"dispatches RPC"| node_chat
node_chat -->|"updates timestamps"| node_serverclock
node_chat -->|"registers streams"| node_registry
node_chat -->|"broadcasts events"| node_broadcast
node_chat -->|"logs events"| node_logging
node_broadcast -->|"reads streams"| node_registry
node_broadcast -->|"sends stream messages"| node_rpcserver

click node_client "https://github.com/shonix/chitchatserver/blob/master/client/client.go"
click node_input "https://github.com/shonix/chitchatserver/blob/master/client/client.go"
click node_clientclock "https://github.com/shonix/chitchatserver/blob/master/client/client.go"
click node_clientio "https://github.com/shonix/chitchatserver/blob/master/client/client.go"
click node_servermain "https://github.com/shonix/chitchatserver/blob/master/server/server.go"
click node_chat "https://github.com/shonix/chitchatserver/blob/master/server/server.go"
click node_serverclock "https://github.com/shonix/chitchatserver/blob/master/server/server.go"
click node_registry "https://github.com/shonix/chitchatserver/blob/master/server/server.go"
click node_broadcast "https://github.com/shonix/chitchatserver/blob/master/server/server.go"
click node_logging "https://github.com/shonix/chitchatserver/blob/master/server/server.go"
click node_clientlogging "https://github.com/shonix/chitchatserver/blob/master/client/client.go"
click node_rpcclient "https://github.com/shonix/chitchatserver/blob/master/grpc/proto_grpc.pb.go"
click node_rpcserver "https://github.com/shonix/chitchatserver/blob/master/grpc/proto_grpc.pb.go"
click node_contract "https://github.com/shonix/chitchatserver/blob/master/grpc/proto.proto"

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_client,node_input,node_clientclock,node_clientio,node_clientlogging,node_user toneBlue
class node_servermain,node_chat,node_serverclock,node_registry,node_broadcast,node_logging toneAmber
class node_rpcclient,node_rpcserver,node_contract toneMint
```

## Components

### Terminal clients

- [Client entry](https://github.com/shonix/chitchatserver/blob/master/client/client.go): `client/client.go`
- [Input and validation](https://github.com/shonix/chitchatserver/blob/master/client/client.go): `client/client.go`
- [Client Lamport clock](https://github.com/shonix/chitchatserver/blob/master/client/client.go): `client/client.go`
- [Client send and display](https://github.com/shonix/chitchatserver/blob/master/client/client.go): `client/client.go`
- [Client logging](https://github.com/shonix/chitchatserver/blob/master/client/client.go): `client/client.go`

### Chat service

- [Server entry](https://github.com/shonix/chitchatserver/blob/master/server/server.go): `server/server.go`
- [Chat stream handler](https://github.com/shonix/chitchatserver/blob/master/server/server.go): `server/server.go`
- [Server Lamport clock](https://github.com/shonix/chitchatserver/blob/master/server/server.go): `server/server.go`
- [Client stream registry](https://github.com/shonix/chitchatserver/blob/master/server/server.go): `server/server.go`
- [Event broadcast](https://github.com/shonix/chitchatserver/blob/master/server/server.go): `server/server.go`
- [Structured logging](https://github.com/shonix/chitchatserver/blob/master/server/server.go): `server/server.go`

### gRPC contract

- [Generated client RPC](https://github.com/shonix/chitchatserver/blob/master/grpc/proto_grpc.pb.go): `grpc/proto_grpc.pb.go`
- [Generated server dispatch](https://github.com/shonix/chitchatserver/blob/master/grpc/proto_grpc.pb.go): `grpc/proto_grpc.pb.go`
- [Stream message contract](https://github.com/shonix/chitchatserver/blob/master/grpc/proto.proto): `grpc/proto.proto`

### Other components

- **Chat user**

## Connections

- Chat user → Client entry: starts client
- Chat user → Input and validation: enters messages
- Client entry → Generated client RPC: opens stream
- Client entry → Client send and display: starts receive loop
- Input and validation → Client send and display: submits text
- Client send and display → Client Lamport clock: timestamps sends
- Client send and display → Generated client RPC: sends and receives
- Input and validation → Client logging: logs rejections
- Client send and display → Client logging: logs activity
- Generated client RPC → Stream message contract: encodes stream
- Stream message contract → Generated server dispatch: defines stream
- Server entry → Generated server dispatch: registers handler
- Server entry → Structured logging: logs lifecycle
- Generated server dispatch → Chat stream handler: dispatches RPC
- Chat stream handler → Server Lamport clock: updates timestamps
- Chat stream handler → Client stream registry: registers streams
- Chat stream handler → Event broadcast: broadcasts events
- Chat stream handler → Structured logging: logs events
- Event broadcast → Client stream registry: reads streams
- Event broadcast → Generated server dispatch: sends stream messages