# claudiovictors/victor architecture

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

- Interactive diagram: https://gitdiagram.com/claudiovictors/victor
- Repository: https://github.com/claudiovictors/victor

## Overview

Victor is a real-time chat app: users authenticate, find people, create direct or group conversations, then exchange text/images and live status events through REST and WebSocket. The Go server routes requests to domain handlers, which coordinate stores, uploads, and the WebSocket hub; the browser UI consumes those APIs and the embedded PWA shell. The graph follows README capabilities and shown call sites. Some handler internals and the application bootstrap were not sampled, so uncertain wiring is omitted.

Main entry points: [`internal/http/router.go`](https://github.com/claudiovictors/victor/blob/main/internal/http/router.go) (HTTP router), [`internal/messages/handlers.go`](https://github.com/claudiovictors/victor/blob/main/internal/messages/handlers.go) (Message handlers), [`internal/auth/handlers.go`](https://github.com/claudiovictors/victor/blob/main/internal/auth/handlers.go) (Auth handlers), [`internal/ws/client.go`](https://github.com/claudiovictors/victor/blob/main/internal/ws/client.go) (WebSocket handler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_browser["Chat interface<br/>[main.js]"]
  node_api_client["API client<br/>[api.js]"]
  node_pwa["PWA shell<br/>[sw.js]"]
end

subgraph group_server["HTTP server"]
  node_router["HTTP router<br/>[router.go]"]
  node_auth_mw["Auth middleware<br/>[middleware.go]"]
end

subgraph group_domain["Chat domains"]
  node_auth_handlers["Auth handlers<br/>[handlers.go]"]
  node_tokens["JWT and passwords<br/>[auth.go]"]
  node_user_handlers["User search<br/>[handlers.go]"]
  node_chat_handlers["Conversation handlers<br/>[handlers.go]"]
  node_message_handlers["Message handlers<br/>[handlers.go]"]
  node_upload_validation["Image validation<br/>[uploads.go]"]
end

subgraph group_infra["Persistence and media"]
  node_user_store["User records<br/>[store.go]"]
  node_chat_store["Conversation records<br/>[store.go]"]
  node_message_store["Message history<br/>[store.go]"]
  node_upload_store["Image storage<br/>[store.go]"]
  node_database[("PostgreSQL<br/>[database.go]")]
  node_file_storage[("Image files")]
end

subgraph group_realtime["Live events"]
  node_ws_handler["WebSocket handler<br/>[client.go]"]
  node_ws_hub["WebSocket hub<br/>[hub.go]"]
end

node_person(("Chat user"))
node_b2[("Backblaze B2")]

node_person -->|"uses"| node_browser
node_browser -->|"calls"| node_api_client
node_api_client -->|"HTTP requests"| node_router
node_router -->|"protects routes"| node_auth_mw
node_router -->|"routes auth"| node_auth_handlers
node_router -->|"routes search"| node_user_handlers
node_router -->|"routes conversations"| node_chat_handlers
node_router -->|"routes messages"| node_message_handlers
node_router -->|"routes WebSocket"| node_ws_handler
node_router -->|"serves embedded shell"| node_pwa
node_auth_handlers -->|"issues tokens"| node_tokens
node_auth_handlers -->|"reads and writes users"| node_user_store
node_auth_handlers -->|"validates avatars"| node_upload_validation
node_auth_handlers -->|"saves avatars"| node_upload_store
node_user_handlers -->|"searches"| node_user_store
node_chat_handlers -->|"manages conversations"| node_chat_store
node_chat_handlers -->|"saves group avatars"| node_upload_store
node_message_handlers -->|"checks membership"| node_chat_store
node_message_handlers -->|"creates and reads"| node_message_store
node_message_handlers -->|"validates images"| node_upload_validation
node_message_handlers -->|"saves images"| node_upload_store
node_message_handlers -->|"broadcasts events"| node_ws_hub
node_chat_handlers -->|"notifies new chats"| node_ws_hub
node_ws_handler -->|"parses token"| node_tokens
node_ws_handler -->|"checks membership and reads"| node_chat_store
node_ws_handler -->|"registers and broadcasts"| node_ws_hub
node_ws_hub -.->|"sends live events"| node_browser
node_browser -.->|"opens live connection"| node_ws_handler
node_upload_store -->|"writes local files"| node_file_storage
node_upload_store -->|"uploads optionally"| node_b2
node_pwa -->|"caches app shell"| node_browser
node_database -->|"runs migrations"| node_database

click node_browser "https://github.com/claudiovictors/victor/blob/main/web/js/main.js"
click node_api_client "https://github.com/claudiovictors/victor/blob/main/web/js/api.js"
click node_pwa "https://github.com/claudiovictors/victor/blob/main/web/sw.js"
click node_router "https://github.com/claudiovictors/victor/blob/main/internal/http/router.go"
click node_auth_mw "https://github.com/claudiovictors/victor/blob/main/internal/http/middleware.go"
click node_auth_handlers "https://github.com/claudiovictors/victor/blob/main/internal/auth/handlers.go"
click node_tokens "https://github.com/claudiovictors/victor/blob/main/internal/auth/auth.go"
click node_user_handlers "https://github.com/claudiovictors/victor/blob/main/internal/users/handlers.go"
click node_user_store "https://github.com/claudiovictors/victor/blob/main/internal/users/store.go"
click node_chat_handlers "https://github.com/claudiovictors/victor/blob/main/internal/chats/handlers.go"
click node_chat_store "https://github.com/claudiovictors/victor/blob/main/internal/chats/store.go"
click node_message_handlers "https://github.com/claudiovictors/victor/blob/main/internal/messages/handlers.go"
click node_message_store "https://github.com/claudiovictors/victor/blob/main/internal/messages/store.go"
click node_upload_validation "https://github.com/claudiovictors/victor/blob/main/internal/uploads/uploads.go"
click node_upload_store "https://github.com/claudiovictors/victor/blob/main/internal/uploads/store.go"
click node_database "https://github.com/claudiovictors/victor/blob/main/internal/database/database.go"
click node_ws_handler "https://github.com/claudiovictors/victor/blob/main/internal/ws/client.go"
click node_ws_hub "https://github.com/claudiovictors/victor/blob/main/internal/ws/hub.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_browser,node_api_client,node_pwa,node_person toneBlue
class node_router,node_auth_mw,node_b2 toneAmber
class node_auth_handlers,node_tokens,node_user_handlers,node_chat_handlers,node_message_handlers,node_upload_validation toneMint
class node_user_store,node_chat_store,node_message_store,node_upload_store,node_database,node_file_storage toneRose
class node_ws_handler,node_ws_hub toneIndigo
```

## Components

### Web client

- [Chat interface](https://github.com/claudiovictors/victor/blob/main/web/js/main.js): `web/js/main.js`
- [API client](https://github.com/claudiovictors/victor/blob/main/web/js/api.js): `web/js/api.js`
- [PWA shell](https://github.com/claudiovictors/victor/blob/main/web/sw.js): `web/sw.js`

### HTTP server

- [HTTP router](https://github.com/claudiovictors/victor/blob/main/internal/http/router.go): `internal/http/router.go`
- [Auth middleware](https://github.com/claudiovictors/victor/blob/main/internal/http/middleware.go): `internal/http/middleware.go`

### Chat domains

- [Auth handlers](https://github.com/claudiovictors/victor/blob/main/internal/auth/handlers.go): `internal/auth/handlers.go`
- [JWT and passwords](https://github.com/claudiovictors/victor/blob/main/internal/auth/auth.go): `internal/auth/auth.go`
- [User search](https://github.com/claudiovictors/victor/blob/main/internal/users/handlers.go): `internal/users/handlers.go`
- [Conversation handlers](https://github.com/claudiovictors/victor/blob/main/internal/chats/handlers.go): `internal/chats/handlers.go`
- [Message handlers](https://github.com/claudiovictors/victor/blob/main/internal/messages/handlers.go): `internal/messages/handlers.go`
- [Image validation](https://github.com/claudiovictors/victor/blob/main/internal/uploads/uploads.go): `internal/uploads/uploads.go`

### Persistence and media

- [User records](https://github.com/claudiovictors/victor/blob/main/internal/users/store.go): `internal/users/store.go`
- [Conversation records](https://github.com/claudiovictors/victor/blob/main/internal/chats/store.go): `internal/chats/store.go`
- [Message history](https://github.com/claudiovictors/victor/blob/main/internal/messages/store.go): `internal/messages/store.go`
- [Image storage](https://github.com/claudiovictors/victor/blob/main/internal/uploads/store.go): `internal/uploads/store.go`
- [PostgreSQL](https://github.com/claudiovictors/victor/blob/main/internal/database/database.go): `internal/database/database.go`
- **Image files**

### Live events

- [WebSocket handler](https://github.com/claudiovictors/victor/blob/main/internal/ws/client.go): `internal/ws/client.go`
- [WebSocket hub](https://github.com/claudiovictors/victor/blob/main/internal/ws/hub.go): `internal/ws/hub.go`

### Other components

- **Chat user**
- **Backblaze B2**

## Connections

- Chat user → Chat interface: uses (evidence: `README.md`)
- Chat interface → API client: calls (evidence: `web/js/main.js`)
- API client → HTTP router: HTTP requests (evidence: `web/js/api.js`)
- HTTP router → Auth middleware: protects routes (evidence: `internal/http/router.go`)
- HTTP router → Auth handlers: routes auth (evidence: `internal/http/router.go`)
- HTTP router → User search: routes search (evidence: `internal/http/router.go`)
- HTTP router → Conversation handlers: routes conversations (evidence: `internal/http/router.go`)
- HTTP router → Message handlers: routes messages (evidence: `internal/http/router.go`)
- HTTP router → WebSocket handler: routes WebSocket (evidence: `internal/http/router.go`)
- HTTP router → PWA shell: serves embedded shell (evidence: `internal/http/router.go`)
- Auth handlers → JWT and passwords: issues tokens (evidence: `internal/auth/handlers.go`)
- Auth handlers → User records: reads and writes users (evidence: `internal/auth/handlers.go`)
- Auth handlers → Image validation: validates avatars (evidence: `internal/auth/handlers.go`)
- Auth handlers → Image storage: saves avatars (evidence: `internal/auth/handlers.go`)
- User search → User records: searches (evidence: `internal/users/handlers.go`)
- Conversation handlers → Conversation records: manages conversations (evidence: `internal/chats/handlers.go`)
- Conversation handlers → Image storage: saves group avatars (evidence: `internal/chats/handlers.go`)
- Message handlers → Conversation records: checks membership (evidence: `internal/messages/handlers.go`)
- Message handlers → Message history: creates and reads (evidence: `internal/messages/handlers.go`)
- Message handlers → Image validation: validates images (evidence: `internal/messages/handlers.go`)
- Message handlers → Image storage: saves images (evidence: `internal/messages/handlers.go`)
- Message handlers → WebSocket hub: broadcasts events (evidence: `internal/messages/handlers.go`)
- Conversation handlers → WebSocket hub: notifies new chats
- WebSocket handler → JWT and passwords: parses token (evidence: `internal/ws/client.go`)
- WebSocket handler → Conversation records: checks membership and reads (evidence: `internal/ws/client.go`)
- WebSocket handler → WebSocket hub: registers and broadcasts (evidence: `internal/ws/client.go`)
- WebSocket hub → Chat interface: sends live events (evidence: `README.md`)
- Chat interface → WebSocket handler: opens live connection (evidence: `README.md`)
- Image storage → Image files: writes local files (evidence: `internal/uploads/store.go`)
- Image storage → Backblaze B2: uploads optionally (evidence: `internal/uploads/store.go`)
- PWA shell → Chat interface: caches app shell (evidence: `web/sw.js`)
- PostgreSQL → PostgreSQL: runs migrations (evidence: `internal/database/database.go`)
