# deus-kh/velo architecture

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

- Interactive diagram: https://gitdiagram.com/deus-kh/velo
- Repository: https://github.com/deus-kh/velo

## Overview

Velo is a React Native secure messenger backed by a Node/Express service. A user authenticates, the client prepares identity and prekeys and connects its socket; a chat then establishes an X3DH session, encrypts messages, and exchanges live traffic or loads encrypted history. The server provides authentication, key bundles, user/conversation APIs, message history, socket delivery, and push support. The map includes documented UI, notification, and security capabilities, but source excerpts are incomplete; unverified links are omitted or marked dashed.

Main entry points: [`chats-server/src/index.ts`](https://github.com/deus-kh/velo/blob/master/chats-server/src/index.ts) (Express service), [`chats-client/src/shared/chat/useChatE2EE.ts`](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/chat/useChatE2EE.ts) (Encrypted chat coordinator), [`chats-client/src/store/auth.store.ts`](https://github.com/deus-kh/velo/blob/master/chats-client/src/store/auth.store.ts) (Auth state), [`chats-server/src/routes/keys.routes.ts`](https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/keys.routes.ts) (Key bundle routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_navigation["App navigation<br/>[Navigation.tsx]"]
  node_authscreens["Login and registration<br/>[LoginScreen.tsx]"]
  node_chatlist["Chat list<br/>[ChatListScreen.tsx]"]
  node_chatscreen["Conversation screen<br/>[ChatScreen.tsx]"]
  node_userflows["User and settings screens<br/>[SettingsScreen.tsx]"]
  node_authstate["Auth state<br/>[auth.store.ts]"]
  node_authapi["Authentication API client<br/>[auth.api.ts]"]
  node_clientapi["Messaging and user APIs<br/>[messages.api.ts]"]
end

subgraph group_security["Encryption and local state"]
  node_chatlogic["Encrypted chat coordinator<br/>[useChatE2EE.ts]"]
  node_crypto["X3DH and message crypto<br/>[x3dh.ts]"]
  node_sessionbootstrap["Session bootstrap"]
  node_sessionstore["Session storage<br/>[sessionStore.ts]"]
  node_localkeys["Identity and prekeys<br/>[prekeys.ts]"]
  node_localpending["Pending messages and keys"]
end

subgraph group_server["Server APIs"]
  node_server["Express service<br/>[index.ts]"]
  node_authroutes["Auth routes<br/>[auth.routes.ts]"]
  node_usersroutes["User routes<br/>[users.routes.ts]"]
  node_keysroutes["Key bundle routes<br/>[keys.routes.ts]"]
  node_convroutes["Conversation routes"]
  node_messagesroutes["Message history routes<br/>[messages.routes.ts]"]
  node_authmiddleware["JWT authorization<br/>[auth.ts]"]
  node_userdb[("User records<br/>[User.ts]")]
  node_messagedb[("Message records<br/>[Message.ts]")]
  node_conversationdb[("Conversation records<br/>[Conversation.ts]")]
end

subgraph group_realtime["Realtime and notifications"]
  node_socketclient["Socket client<br/>[socket.ts]"]
  node_socketmessages["Socket messaging<br/>[messaging.ts]"]
  node_notifications["Push and local notifications<br/>[push.ts]"]
  node_socketserver["Socket delivery<br/>[setupSocket.ts]"]
  node_pushservice["Firebase push<br/>[firebase.ts]"]
end

node_person(("Messenger user"))
node_firebase["Firebase messaging"]

node_person -->|"uses"| node_navigation
node_navigation -->|"routes to"| node_authscreens
node_navigation -->|"routes to"| node_chatlist
node_authscreens -.->|"authenticates via"| node_authstate
node_authstate -->|"calls"| node_authapi
node_authapi -.->|"HTTP auth"| node_authroutes
node_authroutes -->|"reads and writes"| node_userdb
node_authroutes -->|"protects password change"| node_authmiddleware
node_authstate -->|"prepares keys"| node_localkeys
node_authstate -->|"initializes"| node_socketclient
node_authstate -->|"syncs push token"| node_notifications
node_chatlist -.->|"opens chats"| node_chatscreen
node_chatscreen -.->|"uses"| node_chatlogic
node_chatlogic -->|"subscribes"| node_socketmessages
node_chatlogic -->|"establishes sessions"| node_sessionbootstrap
node_chatlogic -->|"loads and deletes"| node_sessionstore
node_chatlogic -->|"queues messages"| node_localpending
node_sessionbootstrap -->|"derives X3DH keys"| node_crypto
node_sessionbootstrap -->|"creates sessions"| node_sessionstore
node_crypto -->|"uses key material"| node_localkeys
node_crypto -.->|"fetches peer bundle"| node_keysroutes
node_chatlogic -.->|"loads history"| node_clientapi
node_clientapi -.->|"HTTP history"| node_messagesroutes
node_messagesroutes -->|"reads and updates"| node_messagedb
node_navigation -.->|"routes to"| node_userflows
node_server -->|"mounts routes"| node_authroutes
node_server -->|"mounts routes"| node_usersroutes
node_server -->|"mounts routes"| node_keysroutes
node_server -->|"mounts routes"| node_convroutes
node_server -->|"mounts routes"| node_messagesroutes
node_server -->|"sets up socket"| node_socketserver
node_usersroutes -->|"protects routes"| node_authmiddleware
node_usersroutes -->|"reads and writes"| node_userdb
node_keysroutes -->|"protects routes"| node_authmiddleware
node_keysroutes -->|"reads and writes"| node_userdb
node_keysroutes -.->|"stores prekeys"| node_server
node_convroutes -->|"protects routes"| node_authmiddleware
node_convroutes -->|"reads and writes"| node_conversationdb
node_messagesroutes -->|"protects routes"| node_authmiddleware
node_socketserver -->|"stores messages"| node_messagedb
node_socketserver -->|"uses conversations"| node_conversationdb
node_socketserver -->|"triggers push"| node_pushservice
node_socketclient -.->|"WebSocket traffic"| node_socketserver
node_notifications -.->|"receives push"| node_firebase
node_pushservice -.->|"sends notifications"| node_firebase

click node_navigation "https://github.com/deus-kh/velo/blob/master/chats-client/src/app/Navigation.tsx"
click node_authscreens "https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/LoginScreen.tsx"
click node_chatlist "https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/ChatListScreen.tsx"
click node_chatscreen "https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/ChatScreen.tsx"
click node_userflows "https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/SettingsScreen.tsx"
click node_authstate "https://github.com/deus-kh/velo/blob/master/chats-client/src/store/auth.store.ts"
click node_authapi "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/api/auth.api.ts"
click node_chatlogic "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/chat/useChatE2EE.ts"
click node_crypto "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/crypto/x3dh.ts"
click node_sessionbootstrap "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/crypto/sessionBootstrap.ts"
click node_sessionstore "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/storage/sessionStore.ts"
click node_localkeys "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/crypto/prekeys.ts"
click node_localpending "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/storage/pendingMessageStore.ts"
click node_clientapi "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/api/messages.api.ts"
click node_socketclient "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/socket/socket.ts"
click node_socketmessages "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/socket/messaging.ts"
click node_notifications "https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/notifications/push.ts"
click node_server "https://github.com/deus-kh/velo/blob/master/chats-server/src/index.ts"
click node_authroutes "https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/auth.routes.ts"
click node_usersroutes "https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/users.routes.ts"
click node_keysroutes "https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/keys.routes.ts"
click node_convroutes "https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/conversations.routes.ts"
click node_messagesroutes "https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/messages.routes.ts"
click node_authmiddleware "https://github.com/deus-kh/velo/blob/master/chats-server/src/middleware/auth.ts"
click node_userdb "https://github.com/deus-kh/velo/blob/master/chats-server/src/models/User.ts"
click node_messagedb "https://github.com/deus-kh/velo/blob/master/chats-server/src/models/Message.ts"
click node_conversationdb "https://github.com/deus-kh/velo/blob/master/chats-server/src/models/Conversation.ts"
click node_socketserver "https://github.com/deus-kh/velo/blob/master/chats-server/src/socket/setupSocket.ts"
click node_pushservice "https://github.com/deus-kh/velo/blob/master/chats-server/src/push/firebase.ts"

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_navigation,node_authscreens,node_chatlist,node_chatscreen,node_userflows,node_authstate,node_authapi,node_clientapi,node_person toneBlue
class node_chatlogic,node_crypto,node_sessionbootstrap,node_sessionstore,node_localkeys,node_localpending toneAmber
class node_server,node_authroutes,node_usersroutes,node_keysroutes,node_convroutes,node_messagesroutes,node_authmiddleware,node_userdb,node_messagedb,node_conversationdb toneMint
class node_socketclient,node_socketmessages,node_notifications,node_socketserver,node_pushservice toneRose
class node_firebase toneIndigo
```

## Components

### Mobile client

- [App navigation](https://github.com/deus-kh/velo/blob/master/chats-client/src/app/Navigation.tsx): `chats-client/src/app/Navigation.tsx`
- [Login and registration](https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/LoginScreen.tsx): `chats-client/src/screens/LoginScreen.tsx`
- [Chat list](https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/ChatListScreen.tsx): `chats-client/src/screens/ChatListScreen.tsx`
- [Conversation screen](https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/ChatScreen.tsx): `chats-client/src/screens/ChatScreen.tsx`
- [User and settings screens](https://github.com/deus-kh/velo/blob/master/chats-client/src/screens/SettingsScreen.tsx): `chats-client/src/screens/SettingsScreen.tsx`
- [Auth state](https://github.com/deus-kh/velo/blob/master/chats-client/src/store/auth.store.ts): `chats-client/src/store/auth.store.ts`
- [Authentication API client](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/api/auth.api.ts): `chats-client/src/shared/api/auth.api.ts`
- [Messaging and user APIs](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/api/messages.api.ts): `chats-client/src/shared/api/messages.api.ts`

### Encryption and local state

- [Encrypted chat coordinator](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/chat/useChatE2EE.ts): `chats-client/src/shared/chat/useChatE2EE.ts`
- [X3DH and message crypto](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/crypto/x3dh.ts): `chats-client/src/shared/crypto/x3dh.ts`
- [Session bootstrap](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/crypto/sessionBootstrap.ts): `chats-client/src/shared/crypto/sessionBootstrap.ts`
- [Session storage](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/storage/sessionStore.ts): `chats-client/src/shared/storage/sessionStore.ts`
- [Identity and prekeys](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/crypto/prekeys.ts): `chats-client/src/shared/crypto/prekeys.ts`
- [Pending messages and keys](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/storage/pendingMessageStore.ts): `chats-client/src/shared/storage/pendingMessageStore.ts`

### Server APIs

- [Express service](https://github.com/deus-kh/velo/blob/master/chats-server/src/index.ts): `chats-server/src/index.ts`
- [Auth routes](https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/auth.routes.ts): `chats-server/src/routes/auth.routes.ts`
- [User routes](https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/users.routes.ts): `chats-server/src/routes/users.routes.ts`
- [Key bundle routes](https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/keys.routes.ts): `chats-server/src/routes/keys.routes.ts`
- [Conversation routes](https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/conversations.routes.ts): `chats-server/src/routes/conversations.routes.ts`
- [Message history routes](https://github.com/deus-kh/velo/blob/master/chats-server/src/routes/messages.routes.ts): `chats-server/src/routes/messages.routes.ts`
- [JWT authorization](https://github.com/deus-kh/velo/blob/master/chats-server/src/middleware/auth.ts): `chats-server/src/middleware/auth.ts`
- [User records](https://github.com/deus-kh/velo/blob/master/chats-server/src/models/User.ts): `chats-server/src/models/User.ts`
- [Message records](https://github.com/deus-kh/velo/blob/master/chats-server/src/models/Message.ts): `chats-server/src/models/Message.ts`
- [Conversation records](https://github.com/deus-kh/velo/blob/master/chats-server/src/models/Conversation.ts): `chats-server/src/models/Conversation.ts`

### Realtime and notifications

- [Socket client](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/socket/socket.ts): `chats-client/src/shared/socket/socket.ts`
- [Socket messaging](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/socket/messaging.ts): `chats-client/src/shared/socket/messaging.ts`
- [Push and local notifications](https://github.com/deus-kh/velo/blob/master/chats-client/src/shared/notifications/push.ts): `chats-client/src/shared/notifications/push.ts`
- [Socket delivery](https://github.com/deus-kh/velo/blob/master/chats-server/src/socket/setupSocket.ts): `chats-server/src/socket/setupSocket.ts`
- [Firebase push](https://github.com/deus-kh/velo/blob/master/chats-server/src/push/firebase.ts): `chats-server/src/push/firebase.ts`

### Other components

- **Messenger user**
- **Firebase messaging**

## Connections

- Messenger user → App navigation: uses (evidence: `chats-client/src/app/Navigation.tsx`)
- App navigation → Login and registration: routes to (evidence: `chats-client/src/app/Navigation.tsx`)
- App navigation → Chat list: routes to (evidence: `chats-client/src/app/Navigation.tsx`)
- Login and registration → Auth state: authenticates via
- Auth state → Authentication API client: calls (evidence: `chats-client/src/store/auth.store.ts`)
- Authentication API client → Auth routes: HTTP auth
- Auth routes → User records: reads and writes (evidence: `chats-server/src/routes/auth.routes.ts`)
- Auth routes → JWT authorization: protects password change (evidence: `chats-server/src/routes/auth.routes.ts`)
- Auth state → Identity and prekeys: prepares keys (evidence: `chats-client/src/store/auth.store.ts`)
- Auth state → Socket client: initializes (evidence: `chats-client/src/store/auth.store.ts`)
- Auth state → Push and local notifications: syncs push token (evidence: `chats-client/src/store/auth.store.ts`)
- Chat list → Conversation screen: opens chats
- Conversation screen → Encrypted chat coordinator: uses
- Encrypted chat coordinator → Socket messaging: subscribes (evidence: `chats-client/src/shared/chat/useChatE2EE.ts`)
- Encrypted chat coordinator → Session bootstrap: establishes sessions (evidence: `chats-client/src/shared/chat/useChatE2EE.ts`)
- Encrypted chat coordinator → Session storage: loads and deletes (evidence: `chats-client/src/shared/chat/useChatE2EE.ts`)
- Encrypted chat coordinator → Pending messages and keys: queues messages (evidence: `chats-client/src/shared/chat/useChatE2EE.ts`)
- Session bootstrap → X3DH and message crypto: derives X3DH keys (evidence: `chats-client/src/shared/crypto/sessionBootstrap.ts`)
- Session bootstrap → Session storage: creates sessions (evidence: `chats-client/src/shared/crypto/sessionBootstrap.ts`)
- X3DH and message crypto → Identity and prekeys: uses key material (evidence: `chats-client/src/shared/crypto/x3dh.ts`)
- X3DH and message crypto → Key bundle routes: fetches peer bundle
- Encrypted chat coordinator → Messaging and user APIs: loads history (evidence: `chats-client/src/shared/chat/useChatE2EE.ts`)
- Messaging and user APIs → Message history routes: HTTP history
- Message history routes → Message records: reads and updates (evidence: `chats-server/src/routes/messages.routes.ts`)
- App navigation → User and settings screens: routes to
- Express service → Auth routes: mounts routes (evidence: `chats-server/src/index.ts`)
- Express service → User routes: mounts routes (evidence: `chats-server/src/index.ts`)
- Express service → Key bundle routes: mounts routes (evidence: `chats-server/src/index.ts`)
- Express service → Conversation routes: mounts routes (evidence: `chats-server/src/index.ts`)
- Express service → Message history routes: mounts routes (evidence: `chats-server/src/index.ts`)
- Express service → Socket delivery: sets up socket (evidence: `chats-server/src/index.ts`)
- User routes → JWT authorization: protects routes (evidence: `chats-server/src/routes/users.routes.ts`)
- User routes → User records: reads and writes (evidence: `chats-server/src/routes/users.routes.ts`)
- Key bundle routes → JWT authorization: protects routes (evidence: `chats-server/src/routes/keys.routes.ts`)
- Key bundle routes → User records: reads and writes (evidence: `chats-server/src/routes/keys.routes.ts`)
- Key bundle routes → Express service: stores prekeys (evidence: `chats-server/src/index.ts`)
- Conversation routes → JWT authorization: protects routes (evidence: `chats-server/src/routes/conversations.routes.ts`)
- Conversation routes → Conversation records: reads and writes (evidence: `chats-server/src/routes/conversations.routes.ts`)
- Message history routes → JWT authorization: protects routes (evidence: `chats-server/src/routes/messages.routes.ts`)
- Socket delivery → Message records: stores messages (evidence: `chats-server/src/socket/setupSocket.ts`)
- Socket delivery → Conversation records: uses conversations (evidence: `chats-server/src/socket/setupSocket.ts`)
- Socket delivery → Firebase push: triggers push (evidence: `chats-server/src/socket/setupSocket.ts`)
- Socket client → Socket delivery: WebSocket traffic
- Push and local notifications → Firebase messaging: receives push
- Firebase push → Firebase messaging: sends notifications
