# imluckyluke/luckyroom architecture

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

- Interactive diagram: https://gitdiagram.com/imluckyluke/luckyroom
- Repository: https://github.com/imluckyluke/luckyroom

## Overview

Chatroom is a Node.js backend for Persian-language group and direct messaging, with real-time synchronization and an administrative dashboard. Users register or sign in, then join rooms or converse privately; REST routes persist chat and account state, while Socket.IO handles live messaging and presence. Separate branches provide secure uploads, stickers, and administration, including RBAC, notifications, logs, and database backup/restore. The README documents capabilities beyond the sampled code; those are represented at subsystem level where the tree supports a path. Some route internals were not sampled, so their detailed call relationships are omitted.

Main entry points: [`server.js`](https://github.com/imluckyluke/luckyroom/blob/main/server.js) (HTTP server), [`db/index.js`](https://github.com/imluckyluke/luckyroom/blob/main/db/index.js) (SQLite database), [`routes/auth.js`](https://github.com/imluckyluke/luckyroom/blob/main/routes/auth.js) (Account routes), [`routes/groups.js`](https://github.com/imluckyluke/luckyroom/blob/main/routes/groups.js) (Group rooms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["HTTP Entry"]
  node_server["HTTP server<br/>[server.js]"]
end

subgraph group_accounts["Accounts &amp; Access"]
  node_authroutes["Account routes<br/>[auth.js]"]
  node_auth["Token authentication<br/>[auth.js]"]
  node_sessions["Device sessions<br/>[sessions.js]"]
end

subgraph group_chat["Chat &amp; Rooms"]
  node_groups["Group rooms<br/>[groups.js]"]
  node_conversations["Direct messages<br/>[conversations.js]"]
end

subgraph group_realtime["Realtime Events"]
  node_socketchat["Live chat<br/>[index.js]"]
  node_presence["Presence<br/>[presence.js]"]
  node_emitter["Socket emitter<br/>[emitter.js]"]
  node_bus["Event bus<br/>[bus.js]"]
  node_listeners["Event listeners<br/>[listeners.js]"]
end

subgraph group_admin["Administration"]
  node_adminroutes["Admin APIs<br/>[admin.js]"]
  node_superadmin["Superadmin console API<br/>[superadmin.js]"]
  node_permissions["RBAC permissions<br/>[permissions.js]"]
  node_backup["Database backup<br/>[backup.js]"]
  node_settings["Runtime settings<br/>[settings.js]"]
end

subgraph group_files["Files &amp; Stickers"]
  node_uploadroutes["Upload endpoints<br/>[uploads.js]"]
  node_upload["Encrypted uploads<br/>[upload.js]"]
  node_stickers["Sticker import<br/>[stickerImport.js]"]
end

node_user(("Chat user"))
node_database[("SQLite database<br/>[index.js]")]

node_user -->|"uses chat"| node_server
node_server -->|"mounts routes"| node_authroutes
node_server -->|"mounts routes"| node_groups
node_server -->|"mounts routes"| node_conversations
node_server -->|"mounts routes"| node_adminroutes
node_server -->|"mounts routes"| node_superadmin
node_server -->|"mounts routes"| node_uploadroutes
node_server -->|"starts sockets"| node_socketchat
node_server -->|"registers listeners"| node_listeners
node_authroutes -->|"reads/writes"| node_database
node_authroutes -->|"issues sessions"| node_sessions
node_auth -->|"checks sessions"| node_sessions
node_authroutes -->|"emits events"| node_bus
node_groups -->|"reads/writes"| node_database
node_groups -->|"emits events"| node_bus
node_groups -->|"broadcasts updates"| node_emitter
node_conversations -->|"reads/writes"| node_database
node_socketchat -->|"reads/writes"| node_database
node_socketchat -->|"tracks presence"| node_presence
node_emitter -->|"broadcasts via"| node_socketchat
node_listeners -->|"subscribes to"| node_bus
node_listeners -->|"logs events"| node_database
node_adminroutes -->|"checks access"| node_permissions
node_adminroutes -->|"updates settings"| node_settings
node_superadmin -->|"checks access"| node_permissions
node_superadmin -->|"manages backups"| node_backup
node_backup -->|"backs up"| node_database
node_uploadroutes -->|"handles uploads"| node_upload
node_uploadroutes -->|"records uploads"| node_database
node_uploadroutes -->|"reads limits"| node_settings
node_stickers -.->|"stores pack metadata"| node_database
node_stickers -.->|"imports Telegram packs"| node_user

click node_server "https://github.com/imluckyluke/luckyroom/blob/main/server.js"
click node_authroutes "https://github.com/imluckyluke/luckyroom/blob/main/routes/auth.js"
click node_auth "https://github.com/imluckyluke/luckyroom/blob/main/middleware/auth.js"
click node_sessions "https://github.com/imluckyluke/luckyroom/blob/main/helpers/sessions.js"
click node_groups "https://github.com/imluckyluke/luckyroom/blob/main/routes/groups.js"
click node_conversations "https://github.com/imluckyluke/luckyroom/blob/main/routes/conversations.js"
click node_socketchat "https://github.com/imluckyluke/luckyroom/blob/main/sockets/index.js"
click node_presence "https://github.com/imluckyluke/luckyroom/blob/main/sockets/presence.js"
click node_emitter "https://github.com/imluckyluke/luckyroom/blob/main/sockets/emitter.js"
click node_bus "https://github.com/imluckyluke/luckyroom/blob/main/events/bus.js"
click node_listeners "https://github.com/imluckyluke/luckyroom/blob/main/events/listeners.js"
click node_adminroutes "https://github.com/imluckyluke/luckyroom/blob/main/routes/admin.js"
click node_superadmin "https://github.com/imluckyluke/luckyroom/blob/main/routes/superadmin.js"
click node_permissions "https://github.com/imluckyluke/luckyroom/blob/main/helpers/permissions.js"
click node_backup "https://github.com/imluckyluke/luckyroom/blob/main/helpers/backup.js"
click node_uploadroutes "https://github.com/imluckyluke/luckyroom/blob/main/routes/uploads.js"
click node_upload "https://github.com/imluckyluke/luckyroom/blob/main/helpers/upload.js"
click node_stickers "https://github.com/imluckyluke/luckyroom/blob/main/helpers/stickerImport.js"
click node_settings "https://github.com/imluckyluke/luckyroom/blob/main/helpers/settings.js"
click node_database "https://github.com/imluckyluke/luckyroom/blob/main/db/index.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_server,node_user toneBlue
class node_authroutes,node_auth,node_sessions,node_database toneAmber
class node_groups,node_conversations toneMint
class node_socketchat,node_presence,node_emitter,node_bus,node_listeners toneRose
class node_adminroutes,node_superadmin,node_permissions,node_backup,node_settings toneIndigo
class node_uploadroutes,node_upload,node_stickers toneTeal
```

## Components

### HTTP Entry

- [HTTP server](https://github.com/imluckyluke/luckyroom/blob/main/server.js): `server.js`

### Accounts & Access

- [Account routes](https://github.com/imluckyluke/luckyroom/blob/main/routes/auth.js): `routes/auth.js`
- [Token authentication](https://github.com/imluckyluke/luckyroom/blob/main/middleware/auth.js): `middleware/auth.js`
- [Device sessions](https://github.com/imluckyluke/luckyroom/blob/main/helpers/sessions.js): `helpers/sessions.js`

### Chat & Rooms

- [Group rooms](https://github.com/imluckyluke/luckyroom/blob/main/routes/groups.js): `routes/groups.js`
- [Direct messages](https://github.com/imluckyluke/luckyroom/blob/main/routes/conversations.js): `routes/conversations.js`

### Realtime Events

- [Live chat](https://github.com/imluckyluke/luckyroom/blob/main/sockets/index.js): `sockets/index.js`
- [Presence](https://github.com/imluckyluke/luckyroom/blob/main/sockets/presence.js): `sockets/presence.js`
- [Socket emitter](https://github.com/imluckyluke/luckyroom/blob/main/sockets/emitter.js): `sockets/emitter.js`
- [Event bus](https://github.com/imluckyluke/luckyroom/blob/main/events/bus.js): `events/bus.js`
- [Event listeners](https://github.com/imluckyluke/luckyroom/blob/main/events/listeners.js): `events/listeners.js`

### Administration

- [Admin APIs](https://github.com/imluckyluke/luckyroom/blob/main/routes/admin.js): `routes/admin.js`
- [Superadmin console API](https://github.com/imluckyluke/luckyroom/blob/main/routes/superadmin.js): `routes/superadmin.js`
- [RBAC permissions](https://github.com/imluckyluke/luckyroom/blob/main/helpers/permissions.js): `helpers/permissions.js`
- [Database backup](https://github.com/imluckyluke/luckyroom/blob/main/helpers/backup.js): `helpers/backup.js`
- [Runtime settings](https://github.com/imluckyluke/luckyroom/blob/main/helpers/settings.js): `helpers/settings.js`

### Files & Stickers

- [Upload endpoints](https://github.com/imluckyluke/luckyroom/blob/main/routes/uploads.js): `routes/uploads.js`
- [Encrypted uploads](https://github.com/imluckyluke/luckyroom/blob/main/helpers/upload.js): `helpers/upload.js`
- [Sticker import](https://github.com/imluckyluke/luckyroom/blob/main/helpers/stickerImport.js): `helpers/stickerImport.js`

### Other components

- **Chat user**
- [SQLite database](https://github.com/imluckyluke/luckyroom/blob/main/db/index.js): `db/index.js`

## Connections

- Chat user → HTTP server: uses chat
- HTTP server → Account routes: mounts routes (evidence: `server.js`)
- HTTP server → Group rooms: mounts routes (evidence: `server.js`)
- HTTP server → Direct messages: mounts routes (evidence: `server.js`)
- HTTP server → Admin APIs: mounts routes (evidence: `server.js`)
- HTTP server → Superadmin console API: mounts routes (evidence: `server.js`)
- HTTP server → Upload endpoints: mounts routes (evidence: `server.js`)
- HTTP server → Live chat: starts sockets (evidence: `server.js`)
- HTTP server → Event listeners: registers listeners (evidence: `server.js`)
- Account routes → SQLite database: reads/writes (evidence: `routes/auth.js`)
- Account routes → Device sessions: issues sessions (evidence: `routes/auth.js`)
- Token authentication → Device sessions: checks sessions (evidence: `middleware/auth.js`)
- Account routes → Event bus: emits events (evidence: `routes/auth.js`)
- Group rooms → SQLite database: reads/writes (evidence: `routes/groups.js`)
- Group rooms → Event bus: emits events (evidence: `routes/groups.js`)
- Group rooms → Socket emitter: broadcasts updates (evidence: `routes/groups.js`)
- Direct messages → SQLite database: reads/writes (evidence: `routes/conversations.js`)
- Live chat → SQLite database: reads/writes (evidence: `sockets/index.js`)
- Live chat → Presence: tracks presence (evidence: `sockets/index.js`)
- Socket emitter → Live chat: broadcasts via (evidence: `sockets/emitter.js`)
- Event listeners → Event bus: subscribes to (evidence: `events/listeners.js`)
- Event listeners → SQLite database: logs events (evidence: `events/listeners.js`)
- Admin APIs → RBAC permissions: checks access (evidence: `routes/admin.js`)
- Admin APIs → Runtime settings: updates settings (evidence: `routes/admin.js`)
- Superadmin console API → RBAC permissions: checks access (evidence: `routes/superadmin.js`)
- Superadmin console API → Database backup: manages backups (evidence: `routes/superadmin.js`)
- Database backup → SQLite database: backs up (evidence: `helpers/backup.js`)
- Upload endpoints → Encrypted uploads: handles uploads (evidence: `routes/uploads.js`)
- Upload endpoints → SQLite database: records uploads (evidence: `routes/uploads.js`)
- Upload endpoints → Runtime settings: reads limits (evidence: `routes/uploads.js`)
- Sticker import → SQLite database: stores pack metadata
- Sticker import → Chat user: imports Telegram packs
