# xcfio/chatio architecture

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

## Overview

Chatio is a real-time chat product: users authenticate in the web app, use chat and account features through the API, and exchange live status and typing events over Socket.IO. The backend also exposes conversation, message, and user operations; shared Drizzle tables and TypeBox types define the data contract. The README documents read receipts and real-time messaging, but the sampled source does not establish which route emits each event, so those specific links are omitted.

Main entry points: [`apps/backend/src/index.ts`](https://github.com/xcfio/chatio/blob/main/apps/backend/src/index.ts) (Fastify server), [`apps/backend/src/database/index.ts`](https://github.com/xcfio/chatio/blob/main/apps/backend/src/database/index.ts) (Database access), [`apps/backend/src/socket/index.ts`](https://github.com/xcfio/chatio/blob/main/apps/backend/src/socket/index.ts) (Socket connection), [`apps/frontend/src/app`](https://github.com/xcfio/chatio/tree/main/apps/frontend/src/app) (Auth and chat UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_webpages["Auth and chat UI"]
  node_fetch["HTTP client<br/>[fetch.ts]"]
  node_websocket["Socket client<br/>[socket.ts]"]
end

subgraph group_api["Backend API"]
  node_server["Fastify server<br/>[index.ts]"]
  node_authroutes["Authentication"]
  node_convroutes["Conversations"]
  node_messageroutes["Messages"]
  node_userroutes["User lookup"]
  node_plugins["Security and API plugins"]
  node_authguard["JWT authentication<br/>[auth.ts]"]
end

subgraph group_realtime["Realtime"]
  node_socketserver["Socket connection<br/>[index.ts]"]
  node_typing["Typing events<br/>[typing.ts]"]
  node_presence["User presence<br/>[user-status.ts]"]
end

subgraph group_data["Shared data"]
  node_dbaccess["Database access<br/>[index.ts]"]
  node_tables[("Chat tables<br/>[index.ts]")]
  node_sharedtypes["Shared types and events<br/>[index.ts]"]
end

node_user(("Chat user"))
node_postgres[("PostgreSQL")]
node_socketio(("Socket.IO clients"))

node_user -->|"uses"| node_webpages
node_webpages -->|"requests data"| node_fetch
node_fetch -->|"HTTP requests"| node_server
node_webpages -->|"connects live"| node_websocket
node_websocket -->|"Socket.IO events"| node_socketio
node_socketio -->|"connects"| node_socketserver
node_server -->|"registers"| node_plugins
node_server -->|"registers routes"| node_authroutes
node_server -->|"registers routes"| node_convroutes
node_server -->|"registers routes"| node_messageroutes
node_server -->|"registers routes"| node_userroutes
node_server -->|"dispatches connections"| node_socketserver
node_authroutes -->|"uses authentication"| node_authguard
node_authroutes -->|"accesses data"| node_dbaccess
node_convroutes -->|"accesses data"| node_dbaccess
node_messageroutes -->|"accesses data"| node_dbaccess
node_userroutes -->|"accesses data"| node_dbaccess
node_socketserver -->|"verifies user"| node_dbaccess
node_socketserver -->|"registers events"| node_typing
node_socketserver -->|"registers events"| node_presence
node_dbaccess -->|"queries"| node_postgres
node_dbaccess -->|"uses tables"| node_tables
node_server -->|"uses contracts"| node_sharedtypes
node_websocket -->|"uses event types"| node_sharedtypes
node_socketserver -->|"uses event types"| node_sharedtypes

click node_webpages "https://github.com/xcfio/chatio/tree/main/apps/frontend/src/app"
click node_fetch "https://github.com/xcfio/chatio/blob/main/apps/frontend/src/lib/fetch.ts"
click node_websocket "https://github.com/xcfio/chatio/blob/main/apps/frontend/src/lib/socket.ts"
click node_server "https://github.com/xcfio/chatio/blob/main/apps/backend/src/index.ts"
click node_authroutes "https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/auth"
click node_convroutes "https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/conversation"
click node_messageroutes "https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/message"
click node_userroutes "https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/user"
click node_plugins "https://github.com/xcfio/chatio/tree/main/apps/backend/src/plugin"
click node_authguard "https://github.com/xcfio/chatio/blob/main/apps/backend/src/decorate/auth.ts"
click node_socketserver "https://github.com/xcfio/chatio/blob/main/apps/backend/src/socket/index.ts"
click node_typing "https://github.com/xcfio/chatio/blob/main/apps/backend/src/socket/typing.ts"
click node_presence "https://github.com/xcfio/chatio/blob/main/apps/backend/src/socket/user-status.ts"
click node_dbaccess "https://github.com/xcfio/chatio/blob/main/apps/backend/src/database/index.ts"
click node_tables "https://github.com/xcfio/chatio/blob/main/lib/schema/src/table/index.ts"
click node_sharedtypes "https://github.com/xcfio/chatio/blob/main/lib/schema/src/types/index.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_webpages,node_fetch,node_websocket,node_user,node_socketio toneBlue
class node_server,node_authroutes,node_convroutes,node_messageroutes,node_userroutes,node_plugins,node_authguard,node_postgres toneAmber
class node_socketserver,node_typing,node_presence toneMint
class node_dbaccess,node_tables,node_sharedtypes toneRose
```

## Components

### Web application

- [Auth and chat UI](https://github.com/xcfio/chatio/tree/main/apps/frontend/src/app): `apps/frontend/src/app`
- [HTTP client](https://github.com/xcfio/chatio/blob/main/apps/frontend/src/lib/fetch.ts): `apps/frontend/src/lib/fetch.ts`
- [Socket client](https://github.com/xcfio/chatio/blob/main/apps/frontend/src/lib/socket.ts): `apps/frontend/src/lib/socket.ts`

### Backend API

- [Fastify server](https://github.com/xcfio/chatio/blob/main/apps/backend/src/index.ts): `apps/backend/src/index.ts`
- [Authentication](https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/auth): `apps/backend/src/routes/auth`
- [Conversations](https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/conversation): `apps/backend/src/routes/conversation`
- [Messages](https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/message): `apps/backend/src/routes/message`
- [User lookup](https://github.com/xcfio/chatio/tree/main/apps/backend/src/routes/user): `apps/backend/src/routes/user`
- [Security and API plugins](https://github.com/xcfio/chatio/tree/main/apps/backend/src/plugin): `apps/backend/src/plugin`
- [JWT authentication](https://github.com/xcfio/chatio/blob/main/apps/backend/src/decorate/auth.ts): `apps/backend/src/decorate/auth.ts`

### Realtime

- [Socket connection](https://github.com/xcfio/chatio/blob/main/apps/backend/src/socket/index.ts): `apps/backend/src/socket/index.ts`
- [Typing events](https://github.com/xcfio/chatio/blob/main/apps/backend/src/socket/typing.ts): `apps/backend/src/socket/typing.ts`
- [User presence](https://github.com/xcfio/chatio/blob/main/apps/backend/src/socket/user-status.ts): `apps/backend/src/socket/user-status.ts`

### Shared data

- [Database access](https://github.com/xcfio/chatio/blob/main/apps/backend/src/database/index.ts): `apps/backend/src/database/index.ts`
- [Chat tables](https://github.com/xcfio/chatio/blob/main/lib/schema/src/table/index.ts): `lib/schema/src/table/index.ts`
- [Shared types and events](https://github.com/xcfio/chatio/blob/main/lib/schema/src/types/index.ts): `lib/schema/src/types/index.ts`

### Other components

- **Chat user**
- **PostgreSQL**
- **Socket.IO clients**

## Connections

- Chat user → Auth and chat UI: uses
- Auth and chat UI → HTTP client: requests data
- HTTP client → Fastify server: HTTP requests
- Auth and chat UI → Socket client: connects live
- Socket client → Socket.IO clients: Socket.IO events
- Socket.IO clients → Socket connection: connects
- Fastify server → Security and API plugins: registers
- Fastify server → Authentication: registers routes
- Fastify server → Conversations: registers routes
- Fastify server → Messages: registers routes
- Fastify server → User lookup: registers routes
- Fastify server → Socket connection: dispatches connections
- Authentication → JWT authentication: uses authentication
- Authentication → Database access: accesses data
- Conversations → Database access: accesses data
- Messages → Database access: accesses data
- User lookup → Database access: accesses data
- Socket connection → Database access: verifies user
- Socket connection → Typing events: registers events
- Socket connection → User presence: registers events
- Database access → PostgreSQL: queries
- Database access → Chat tables: uses tables
- Fastify server → Shared types and events: uses contracts
- Socket client → Shared types and events: uses event types
- Socket connection → Shared types and events: uses event types