# niranjan20069019-pixel/chatsphere architecture

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

- Interactive diagram: https://gitdiagram.com/niranjan20069019-pixel/chatsphere
- Repository: https://github.com/niranjan20069019-pixel/chatsphere

## Overview

ChatSphere is a username-based real-time messaging platform. Users register or sign in, connect with friends, exchange direct or group messages and media, then manage profiles, notifications, and account settings. The web app reaches the Express API through its API client; Socket.IO supports live communication and call signaling. The backend controllers implement domain operations and persist state through Prisma to PostgreSQL. The README documents calls, browser notifications, and Cloudinary as product capabilities, but their detailed wiring is not fully visible in the sampled source; those links are shown at subsystem level.

Main entry points: [`apps/server/src/routes/api.ts`](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/routes/api.ts) (API routes), [`apps/server/src/config/database.ts`](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/config/database.ts) (Prisma client), [`apps/web/src/app`](https://github.com/niranjan20069019-pixel/chatsphere/tree/main/apps/web/src/app) (Web pages), [`apps/server/src/controllers/auth.controller.ts`](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/auth.controller.ts) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webapp["Web pages"]
  node_chatui["Chat interface"]
  node_callui["Call overlay<br/>[CallOverlay.tsx]"]
  node_apiclient["API client<br/>[api.ts]"]
  node_socketclient["Socket client<br/>[socket.ts]"]
  node_socketprovider["Socket provider<br/>[SocketProvider.tsx]"]
end

subgraph group_identity["Identity and social"]
  node_auth["Authentication<br/>[auth.controller.ts]"]
  node_profiles["Profiles and settings<br/>[user.controller.ts]"]
  node_friendships["Friends and reports"]
end

subgraph group_communication["Messaging and calls"]
  node_directmessages["Direct messages"]
  node_groups["Groups and messages"]
  node_uploads["Media uploads"]
  node_realtime["Realtime events<br/>[index.ts]"]
  node_notifications["Notifications"]
end

subgraph group_platform["Server platform"]
  node_admin["Administration"]
  node_routes["API routes<br/>[api.ts]"]
  node_server["Express server<br/>[index.ts]"]
  node_emailservice["Email service<br/>[email.service.ts]"]
end

subgraph group_state["Persistence and integrations"]
  node_prisma["Prisma client<br/>[database.ts]"]
  node_database[("PostgreSQL")]
  node_cloudinary[("Cloudinary storage")]
  node_smtp["SMTP email"]
  node_browser["Browser notifications"]
  node_webrtc(("WebRTC peers"))
end

node_user(("ChatSphere user"))

node_user -->|"uses"| node_webapp
node_webapp -->|"requests data"| node_apiclient
node_chatui -->|"requests chats"| node_apiclient
node_callui -->|"uses signaling"| node_socketprovider
node_socketprovider -->|"connects through"| node_socketclient
node_apiclient -->|"sends HTTP"| node_server
node_socketclient -->|"connects to"| node_realtime
node_server -->|"dispatches API"| node_routes
node_routes -->|"dispatches auth"| node_auth
node_routes -->|"dispatches profile"| node_profiles
node_routes -->|"dispatches friends"| node_friendships
node_routes -->|"dispatches messages"| node_directmessages
node_routes -->|"dispatches groups"| node_groups
node_routes -->|"dispatches uploads"| node_uploads
node_routes -->|"dispatches notifications"| node_notifications
node_routes -->|"dispatches admin"| node_admin
node_auth -->|"reads and writes"| node_prisma
node_auth -->|"sends account email"| node_emailservice
node_profiles -->|"reads and writes"| node_prisma
node_friendships -->|"reads and writes"| node_prisma
node_directmessages -->|"reads and writes"| node_prisma
node_groups -->|"reads and writes"| node_prisma
node_uploads -.->|"stores media"| node_cloudinary
node_notifications -->|"reads and writes"| node_prisma
node_admin -->|"reads and writes"| node_prisma
node_prisma -->|"queries"| node_database
node_emailservice -.->|"sends email"| node_smtp
node_realtime -.->|"signals calls"| node_webrtc
node_webapp -.->|"shows notifications"| node_browser

click node_webapp "https://github.com/niranjan20069019-pixel/chatsphere/tree/main/apps/web/src/app"
click node_chatui "https://github.com/niranjan20069019-pixel/chatsphere/tree/main/apps/web/src/components/chat"
click node_callui "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/components/call/CallOverlay.tsx"
click node_apiclient "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/lib/api.ts"
click node_socketclient "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/lib/socket.ts"
click node_socketprovider "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/components/providers/SocketProvider.tsx"
click node_auth "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/auth.controller.ts"
click node_profiles "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/user.controller.ts"
click node_friendships "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/friends.controller.ts"
click node_directmessages "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/messages.controller.ts"
click node_groups "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/groups.controller.ts"
click node_uploads "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/upload.controller.ts"
click node_realtime "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/sockets/index.ts"
click node_notifications "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/notifications.controller.ts"
click node_admin "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/admin.controller.ts"
click node_routes "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/routes/api.ts"
click node_server "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/index.ts"
click node_emailservice "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/services/email.service.ts"
click node_prisma "https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/config/database.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_webapp,node_chatui,node_callui,node_apiclient,node_socketclient,node_socketprovider,node_user toneBlue
class node_auth,node_profiles,node_friendships toneAmber
class node_directmessages,node_groups,node_uploads,node_realtime,node_notifications toneMint
class node_admin,node_routes,node_server,node_emailservice toneRose
class node_prisma,node_database,node_cloudinary,node_smtp,node_browser,node_webrtc toneIndigo
```

## Components

### Web experience

- [Web pages](https://github.com/niranjan20069019-pixel/chatsphere/tree/main/apps/web/src/app): `apps/web/src/app`
- [Chat interface](https://github.com/niranjan20069019-pixel/chatsphere/tree/main/apps/web/src/components/chat): `apps/web/src/components/chat`
- [Call overlay](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/components/call/CallOverlay.tsx): `apps/web/src/components/call/CallOverlay.tsx`
- [API client](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/lib/api.ts): `apps/web/src/lib/api.ts`
- [Socket client](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/lib/socket.ts): `apps/web/src/lib/socket.ts`
- [Socket provider](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/web/src/components/providers/SocketProvider.tsx): `apps/web/src/components/providers/SocketProvider.tsx`

### Identity and social

- [Authentication](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/auth.controller.ts): `apps/server/src/controllers/auth.controller.ts`
- [Profiles and settings](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/user.controller.ts): `apps/server/src/controllers/user.controller.ts`
- [Friends and reports](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/friends.controller.ts): `apps/server/src/controllers/friends.controller.ts`

### Messaging and calls

- [Direct messages](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/messages.controller.ts): `apps/server/src/controllers/messages.controller.ts`
- [Groups and messages](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/groups.controller.ts): `apps/server/src/controllers/groups.controller.ts`
- [Media uploads](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/upload.controller.ts): `apps/server/src/controllers/upload.controller.ts`
- [Realtime events](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/sockets/index.ts): `apps/server/src/sockets/index.ts`
- [Notifications](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/notifications.controller.ts): `apps/server/src/controllers/notifications.controller.ts`

### Server platform

- [Administration](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/controllers/admin.controller.ts): `apps/server/src/controllers/admin.controller.ts`
- [API routes](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/routes/api.ts): `apps/server/src/routes/api.ts`
- [Express server](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/index.ts): `apps/server/src/index.ts`
- [Email service](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/services/email.service.ts): `apps/server/src/services/email.service.ts`

### Persistence and integrations

- [Prisma client](https://github.com/niranjan20069019-pixel/chatsphere/blob/main/apps/server/src/config/database.ts): `apps/server/src/config/database.ts`
- **PostgreSQL**
- **Cloudinary storage**
- **SMTP email**
- **Browser notifications**
- **WebRTC peers**

### Other components

- **ChatSphere user**

## Connections

- ChatSphere user → Web pages: uses
- Web pages → API client: requests data
- Chat interface → API client: requests chats
- Call overlay → Socket provider: uses signaling
- Socket provider → Socket client: connects through
- API client → Express server: sends HTTP
- Socket client → Realtime events: connects to
- Express server → API routes: dispatches API
- API routes → Authentication: dispatches auth
- API routes → Profiles and settings: dispatches profile
- API routes → Friends and reports: dispatches friends
- API routes → Direct messages: dispatches messages
- API routes → Groups and messages: dispatches groups
- API routes → Media uploads: dispatches uploads
- API routes → Notifications: dispatches notifications
- API routes → Administration: dispatches admin
- Authentication → Prisma client: reads and writes
- Authentication → Email service: sends account email
- Profiles and settings → Prisma client: reads and writes
- Friends and reports → Prisma client: reads and writes
- Direct messages → Prisma client: reads and writes
- Groups and messages → Prisma client: reads and writes
- Media uploads → Cloudinary storage: stores media
- Notifications → Prisma client: reads and writes
- Administration → Prisma client: reads and writes
- Prisma client → PostgreSQL: queries
- Email service → SMTP email: sends email
- Realtime events → WebRTC peers: signals calls
- Web pages → Browser notifications: shows notifications