# minghsu0107/go-random-chat architecture

> Architecture diagram of the GitHub repository minghsu0107/go-random-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/minghsu0107/go-random-chat
- Repository: https://github.com/minghsu0107/go-random-chat
- Video tour (about a minute): https://gitdiagram.com/minghsu0107/go-random-chat/video

## Overview

Go Random Chat is a stateless, multi-service real-time chat platform. Users enter through the web service, authenticate through the user service, request a match, then communicate in a chat channel; messages are persisted and published for forwarding to the chat server serving their recipients. File upload and channel-level access are separate capabilities. The graph reflects documented service roles and sampled service behavior; handler-level wiring was not sampled, so uncertain call paths are omitted.

Main entry points: [`pkg/chat/service.go`](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/service.go) (Channel and messages), [`pkg/user/service.go`](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/user/service.go) (User service), [`pkg/match/service.go`](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/match/service.go) (Matching logic), [`pkg/chat/router.go`](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/router.go) (Chat HTTP/gRPC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and identity"]
  node_web["Web frontend<br/>[router.go]"]
  node_user["User service<br/>[service.go]"]
  node_userapi["User HTTP/gRPC<br/>[router.go]"]
  node_oauth["Google OAuth"]
end

subgraph group_match["Matching"]
  node_matchapi["Match HTTP<br/>[router.go]"]
  node_matching["Matching logic<br/>[service.go]"]
  node_matchstate[("Match state<br/>[repo.go]")]
end

subgraph group_messaging["Messaging"]
  node_chatapi["Chat HTTP/gRPC<br/>[router.go]"]
  node_chatlogic["Channel and messages<br/>[service.go]"]
  node_chatstore[("Chat repositories<br/>[repo.go]")]
  node_cache[("Chat cache<br/>[repo_cache.go]")]
  node_kafka["Kafka<br/>[kafka.go]"]
  node_forwarder["Message forwarder<br/>[service.go]"]
  node_forwardrpc["Forwarder gRPC<br/>[router.go]"]
end

subgraph group_files["File uploads"]
  node_uploader["Uploader API<br/>[router.go]"]
  node_presigner["Presigned access<br/>[presigner.go]"]
  node_objectstore[("S3 storage")]
end

node_enduser(("Chat user"))
node_redis[("Redis<br/>[redis.go]")]
node_cassandra[("Cassandra<br/>[cassandra.go]")]

node_enduser -->|"opens app"| node_web
node_enduser -->|"authenticates"| node_userapi
node_userapi -->|"handles identity"| node_user
node_user -.->|"fetches profile"| node_oauth
node_user -->|"stores sessions"| node_redis
node_enduser -->|"requests match"| node_matchapi
node_matchapi -->|"dispatches"| node_matching
node_matching -->|"updates waitlist"| node_matchstate
node_matching -->|"creates channel"| node_chatapi
node_enduser -->|"joins channel"| node_chatapi
node_chatapi -->|"dispatches"| node_chatlogic
node_chatlogic -->|"persists messages"| node_chatstore
node_chatlogic -->|"reads and writes"| node_cache
node_chatlogic -->|"publishes messages"| node_kafka
node_kafka -->|"delivers events"| node_forwarder
node_forwarder -->|"routes messages"| node_forwardrpc
node_enduser -->|"uploads files"| node_uploader
node_uploader -->|"creates access URL"| node_presigner
node_presigner -.->|"signs object access"| node_objectstore
node_chatlogic -->|"stores chat history"| node_cassandra

click node_web "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/web/router.go"
click node_user "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/user/service.go"
click node_userapi "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/user/router.go"
click node_matchapi "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/match/router.go"
click node_matching "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/match/service.go"
click node_matchstate "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/match/repo.go"
click node_chatapi "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/router.go"
click node_chatlogic "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/service.go"
click node_chatstore "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/repo.go"
click node_cache "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/repo_cache.go"
click node_kafka "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/infra/kafka.go"
click node_forwarder "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/forwarder/service.go"
click node_forwardrpc "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/forwarder/router.go"
click node_uploader "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/uploader/router.go"
click node_presigner "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/uploader/presigner.go"
click node_redis "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/infra/redis.go"
click node_cassandra "https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/infra/cassandra.go"

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_web,node_user,node_userapi,node_oauth,node_enduser toneBlue
class node_matchapi,node_matching,node_matchstate,node_redis,node_cassandra toneAmber
class node_chatapi,node_chatlogic,node_chatstore,node_cache,node_kafka,node_forwarder,node_forwardrpc toneMint
class node_uploader,node_presigner,node_objectstore toneRose
```

## Components

### Entry and identity

- [Web frontend](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/web/router.go): `pkg/web/router.go`
- [User service](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/user/service.go): `pkg/user/service.go`
- [User HTTP/gRPC](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/user/router.go): `pkg/user/router.go`
- **Google OAuth**

### Matching

- [Match HTTP](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/match/router.go): `pkg/match/router.go`
- [Matching logic](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/match/service.go): `pkg/match/service.go`
- [Match state](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/match/repo.go): `pkg/match/repo.go`

### Messaging

- [Chat HTTP/gRPC](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/router.go): `pkg/chat/router.go`
- [Channel and messages](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/service.go): `pkg/chat/service.go`
- [Chat repositories](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/repo.go): `pkg/chat/repo.go`
- [Chat cache](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/chat/repo_cache.go): `pkg/chat/repo_cache.go`
- [Kafka](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/infra/kafka.go): `pkg/infra/kafka.go`
- [Message forwarder](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/forwarder/service.go): `pkg/forwarder/service.go`
- [Forwarder gRPC](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/forwarder/router.go): `pkg/forwarder/router.go`

### File uploads

- [Uploader API](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/uploader/router.go): `pkg/uploader/router.go`
- [Presigned access](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/uploader/presigner.go): `pkg/uploader/presigner.go`
- **S3 storage**

### Other components

- **Chat user**
- [Redis](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/infra/redis.go): `pkg/infra/redis.go`
- [Cassandra](https://github.com/minghsu0107/go-random-chat/blob/kafka/pkg/infra/cassandra.go): `pkg/infra/cassandra.go`

## Connections

- Chat user → Web frontend: opens app
- Chat user → User HTTP/gRPC: authenticates
- User HTTP/gRPC → User service: handles identity
- User service → Google OAuth: fetches profile
- User service → Redis: stores sessions
- Chat user → Match HTTP: requests match
- Match HTTP → Matching logic: dispatches
- Matching logic → Match state: updates waitlist
- Matching logic → Chat HTTP/gRPC: creates channel
- Chat user → Chat HTTP/gRPC: joins channel
- Chat HTTP/gRPC → Channel and messages: dispatches
- Channel and messages → Chat repositories: persists messages
- Channel and messages → Chat cache: reads and writes
- Channel and messages → Kafka: publishes messages
- Kafka → Message forwarder: delivers events
- Message forwarder → Forwarder gRPC: routes messages
- Chat user → Uploader API: uploads files
- Uploader API → Presigned access: creates access URL
- Presigned access → S3 storage: signs object access
- Channel and messages → Cassandra: stores chat history