# brillery/feedback-system architecture

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

- Interactive diagram: https://gitdiagram.com/brillery/feedback-system
- Repository: https://github.com/brillery/feedback-system

## Overview

这是一个面向用户、商家和管理员的反馈与消息系统。主要流程是用户登录后提交反馈，系统保存反馈及初始消息并通知接收方；各角色随后查看反馈、往来消息或更新处理状态，实时通知通过 WebSocket 推送。README 描述了连接与事件机制，采样代码也确认反馈服务会调用实时层。部分服务和前端源码未采样，相关细节仅按 README 与目录能力概括。

Main entry points: [`cmd/main.go`](https://github.com/brillery/feedback-system/blob/master/cmd/main.go) (HTTP server), [`pkg/ws/handler.go`](https://github.com/brillery/feedback-system/blob/master/pkg/ws/handler.go) (WebSocket endpoint), [`internal/service/feedback.go`](https://github.com/brillery/feedback-system/blob/master/internal/service/feedback.go) (Feedback service), [`internal/service/feedback_message.go`](https://github.com/brillery/feedback-system/blob/master/internal/service/feedback_message.go) (Message service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Web clients"]
  node_user_ui["User interface<br/>[user.js]"]
  node_merchant_ui["Merchant interface<br/>[merchant.js]"]
  node_admin_ui["Admin interface<br/>[admin.js]"]
  node_register_ui["Registration interface<br/>[register.js]"]
  node_browser_socket["Browser WebSocket<br/>[config.js]"]
end

subgraph group_http["HTTP API"]
  node_server["HTTP server<br/>[main.go]"]
  node_auth["Authentication<br/>[auth.go]"]
  node_user_handler["User endpoints<br/>[user.go]"]
  node_feedback_handler["Feedback endpoints<br/>[feedback.go]"]
  node_message_handler["Message endpoints"]
  node_upload_handler["Image upload<br/>[upload.go]"]
end

subgraph group_domain["Feedback domain"]
  node_feedback_service["Feedback service<br/>[feedback.go]"]
  node_message_service["Message service"]
  node_user_service["User service<br/>[user.go]"]
end

subgraph group_realtime["Realtime messaging"]
  node_ws_http["WebSocket endpoint<br/>[handler.go]"]
  node_ws_client["Connection pumps<br/>[client.go]"]
  node_ws_hub["Connection hub<br/>[hub.go]"]
  node_ws_client_model["Client connection<br/>[ws_client.go]"]
end

subgraph group_storage["Persistence"]
  node_feedback_repo["Feedback repository<br/>[feedback.go]"]
  node_message_repo["Message repository"]
  node_user_repo["User repository<br/>[user.go]"]
  node_database[("MySQL database<br/>[db.go]")]
end

node_user_actor(("User"))
node_merchant_actor(("Merchant"))
node_admin_actor(("Administrator"))
node_uploads[("Uploaded images")]

node_user_actor -->|"uses"| node_user_ui
node_merchant_actor -->|"uses"| node_merchant_ui
node_admin_actor -->|"uses"| node_admin_ui
node_user_actor -->|"registers"| node_register_ui
node_user_ui -->|"API requests"| node_server
node_merchant_ui -->|"API requests"| node_server
node_admin_ui -->|"API requests"| node_server
node_register_ui -->|"API requests"| node_server
node_server -->|"guards routes"| node_auth
node_server -->|"routes requests"| node_user_handler
node_server -->|"routes requests"| node_feedback_handler
node_server -->|"routes requests"| node_message_handler
node_server -->|"routes requests"| node_upload_handler
node_user_handler -->|"calls"| node_user_service
node_auth -->|"validates token"| node_user_service
node_feedback_handler -->|"calls"| node_feedback_service
node_message_handler -->|"calls"| node_message_service
node_feedback_service -->|"reads and writes"| node_feedback_repo
node_feedback_service -->|"creates and deletes"| node_message_repo
node_feedback_service -->|"looks up users"| node_user_repo
node_message_service -->|"reads and writes"| node_message_repo
node_message_service -->|"reads feedback"| node_feedback_repo
node_message_service -->|"looks up users"| node_user_repo
node_user_service -->|"reads and writes"| node_user_repo
node_feedback_repo -->|"persists feedback"| node_database
node_message_repo -->|"persists messages"| node_database
node_user_repo -->|"persists users"| node_database
node_upload_handler -->|"stores images"| node_uploads
node_user_ui -->|"opens connection"| node_browser_socket
node_merchant_ui -->|"opens connection"| node_browser_socket
node_admin_ui -->|"opens connection"| node_browser_socket
node_browser_socket -->|"connects"| node_ws_http
node_ws_http -->|"creates client"| node_ws_client_model
node_ws_http -->|"registers client"| node_ws_hub
node_ws_http -->|"starts pumps"| node_ws_client
node_ws_client -->|"dispatches events"| node_ws_hub
node_ws_hub -->|"queues delivery"| node_ws_client_model
node_feedback_service -->|"notifies changes"| node_ws_http
node_message_service -->|"notifies messages"| node_ws_http

click node_user_ui "https://github.com/brillery/feedback-system/blob/master/static/js/user.js"
click node_merchant_ui "https://github.com/brillery/feedback-system/blob/master/static/js/merchant.js"
click node_admin_ui "https://github.com/brillery/feedback-system/blob/master/static/js/admin.js"
click node_register_ui "https://github.com/brillery/feedback-system/blob/master/static/js/register.js"
click node_server "https://github.com/brillery/feedback-system/blob/master/cmd/main.go"
click node_auth "https://github.com/brillery/feedback-system/blob/master/internal/middleware/auth.go"
click node_user_handler "https://github.com/brillery/feedback-system/blob/master/internal/handler/user.go"
click node_feedback_handler "https://github.com/brillery/feedback-system/blob/master/internal/handler/feedback.go"
click node_message_handler "https://github.com/brillery/feedback-system/blob/master/internal/handler/feedback_message.go"
click node_upload_handler "https://github.com/brillery/feedback-system/blob/master/internal/handler/upload.go"
click node_feedback_service "https://github.com/brillery/feedback-system/blob/master/internal/service/feedback.go"
click node_message_service "https://github.com/brillery/feedback-system/blob/master/internal/service/feedback_message.go"
click node_user_service "https://github.com/brillery/feedback-system/blob/master/internal/service/user.go"
click node_feedback_repo "https://github.com/brillery/feedback-system/blob/master/internal/repository/feedback.go"
click node_message_repo "https://github.com/brillery/feedback-system/blob/master/internal/repository/feedback_message.go"
click node_user_repo "https://github.com/brillery/feedback-system/blob/master/internal/repository/user.go"
click node_database "https://github.com/brillery/feedback-system/blob/master/pkg/db/db.go"
click node_ws_http "https://github.com/brillery/feedback-system/blob/master/pkg/ws/handler.go"
click node_ws_client "https://github.com/brillery/feedback-system/blob/master/pkg/ws/client.go"
click node_ws_hub "https://github.com/brillery/feedback-system/blob/master/pkg/ws/hub.go"
click node_ws_client_model "https://github.com/brillery/feedback-system/blob/master/pkg/ws/ws_client.go"
click node_browser_socket "https://github.com/brillery/feedback-system/blob/master/static/js/config.js"

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_user_ui,node_merchant_ui,node_admin_ui,node_register_ui,node_browser_socket,node_user_actor toneBlue
class node_server,node_auth,node_user_handler,node_feedback_handler,node_message_handler,node_upload_handler,node_uploads toneAmber
class node_feedback_service,node_message_service,node_user_service toneMint
class node_ws_http,node_ws_client,node_ws_hub,node_ws_client_model toneRose
class node_feedback_repo,node_message_repo,node_user_repo,node_database,node_merchant_actor,node_admin_actor toneIndigo
```

## Components

### Web clients

- [User interface](https://github.com/brillery/feedback-system/blob/master/static/js/user.js): `static/js/user.js`
- [Merchant interface](https://github.com/brillery/feedback-system/blob/master/static/js/merchant.js): `static/js/merchant.js`
- [Admin interface](https://github.com/brillery/feedback-system/blob/master/static/js/admin.js): `static/js/admin.js`
- [Registration interface](https://github.com/brillery/feedback-system/blob/master/static/js/register.js): `static/js/register.js`
- [Browser WebSocket](https://github.com/brillery/feedback-system/blob/master/static/js/config.js): `static/js/config.js`

### HTTP API

- [HTTP server](https://github.com/brillery/feedback-system/blob/master/cmd/main.go): `cmd/main.go`
- [Authentication](https://github.com/brillery/feedback-system/blob/master/internal/middleware/auth.go): `internal/middleware/auth.go`
- [User endpoints](https://github.com/brillery/feedback-system/blob/master/internal/handler/user.go): `internal/handler/user.go`
- [Feedback endpoints](https://github.com/brillery/feedback-system/blob/master/internal/handler/feedback.go): `internal/handler/feedback.go`
- [Message endpoints](https://github.com/brillery/feedback-system/blob/master/internal/handler/feedback_message.go): `internal/handler/feedback_message.go`
- [Image upload](https://github.com/brillery/feedback-system/blob/master/internal/handler/upload.go): `internal/handler/upload.go`

### Feedback domain

- [Feedback service](https://github.com/brillery/feedback-system/blob/master/internal/service/feedback.go): `internal/service/feedback.go`
- [Message service](https://github.com/brillery/feedback-system/blob/master/internal/service/feedback_message.go): `internal/service/feedback_message.go`
- [User service](https://github.com/brillery/feedback-system/blob/master/internal/service/user.go): `internal/service/user.go`

### Realtime messaging

- [WebSocket endpoint](https://github.com/brillery/feedback-system/blob/master/pkg/ws/handler.go): `pkg/ws/handler.go`
- [Connection pumps](https://github.com/brillery/feedback-system/blob/master/pkg/ws/client.go): `pkg/ws/client.go`
- [Connection hub](https://github.com/brillery/feedback-system/blob/master/pkg/ws/hub.go): `pkg/ws/hub.go`
- [Client connection](https://github.com/brillery/feedback-system/blob/master/pkg/ws/ws_client.go): `pkg/ws/ws_client.go`

### Persistence

- [Feedback repository](https://github.com/brillery/feedback-system/blob/master/internal/repository/feedback.go): `internal/repository/feedback.go`
- [Message repository](https://github.com/brillery/feedback-system/blob/master/internal/repository/feedback_message.go): `internal/repository/feedback_message.go`
- [User repository](https://github.com/brillery/feedback-system/blob/master/internal/repository/user.go): `internal/repository/user.go`
- [MySQL database](https://github.com/brillery/feedback-system/blob/master/pkg/db/db.go): `pkg/db/db.go`

### Other components

- **User**
- **Merchant**
- **Administrator**
- **Uploaded images**

## Connections

- User → User interface: uses
- Merchant → Merchant interface: uses
- Administrator → Admin interface: uses
- User → Registration interface: registers
- User interface → HTTP server: API requests
- Merchant interface → HTTP server: API requests
- Admin interface → HTTP server: API requests
- Registration interface → HTTP server: API requests
- HTTP server → Authentication: guards routes
- HTTP server → User endpoints: routes requests
- HTTP server → Feedback endpoints: routes requests
- HTTP server → Message endpoints: routes requests
- HTTP server → Image upload: routes requests
- User endpoints → User service: calls
- Authentication → User service: validates token
- Feedback endpoints → Feedback service: calls
- Message endpoints → Message service: calls
- Feedback service → Feedback repository: reads and writes
- Feedback service → Message repository: creates and deletes
- Feedback service → User repository: looks up users
- Message service → Message repository: reads and writes
- Message service → Feedback repository: reads feedback
- Message service → User repository: looks up users
- User service → User repository: reads and writes
- Feedback repository → MySQL database: persists feedback
- Message repository → MySQL database: persists messages
- User repository → MySQL database: persists users
- Image upload → Uploaded images: stores images
- User interface → Browser WebSocket: opens connection
- Merchant interface → Browser WebSocket: opens connection
- Admin interface → Browser WebSocket: opens connection
- Browser WebSocket → WebSocket endpoint: connects
- WebSocket endpoint → Client connection: creates client
- WebSocket endpoint → Connection hub: registers client
- WebSocket endpoint → Connection pumps: starts pumps
- Connection pumps → Connection hub: dispatches events
- Connection hub → Client connection: queues delivery
- Feedback service → WebSocket endpoint: notifies changes
- Message service → WebSocket endpoint: notifies messages