# sadhguru-slayer/fieldchat architecture

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

- Interactive diagram: https://gitdiagram.com/sadhguru-slayer/fieldchat
- Repository: https://github.com/sadhguru-slayer/fieldchat

## Overview

FieldChat is an asynchronous chat backend. Users authenticate, connect through REST or WebSockets, manage conversations, and exchange persistent messages plus transient typing/presence events. Persistent message changes are recorded with outbox events, streamed through Redis, and delivered to WebSocket clients; ephemeral events use Pub/Sub. The graph also preserves documented profile, administration, storage, and push-notification capabilities. Several routes and workers are represented by their exact tree paths but were not sampled, so their internal call wiring is intentionally limited to documented relationships.

Main entry points: [`app/redis_client.py`](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis_client.py) (Redis state and streams), [`app/main.py`](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/main.py) (FastAPI application), [`app/router/auth.py`](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/auth.py) (Authentication routes), [`app/ws/manager.py`](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/ws/manager.py) (Connection manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and identity"]
  node_app["FastAPI application<br/>[main.py]"]
  node_auth_routes["Authentication routes<br/>[auth.py]"]
  node_identity["User and token services<br/>[user.py]"]
  node_jwt["JWT security<br/>[auth.py]"]
  node_users_model["User model<br/>[user.py]"]
  node_admin["Admin operations<br/>[message.py]"]
end

subgraph group_chat["Chat domain"]
  node_chat_routes["Conversation routes<br/>[chat.py]"]
  node_message_routes["Message routes<br/>[messages.py]"]
  node_chat_service["Message processing<br/>[messages.py]"]
  node_chat_models["Messages and chat models<br/>[messages.py]"]
  node_storage["Attachment storage<br/>[storage_service.py]"]
end

subgraph group_realtime["Realtime delivery"]
  node_ws_socket["WebSocket event handling<br/>[sockets.py]"]
  node_ws_manager["Connection manager<br/>[manager.py]"]
  node_redis_handlers["Redis event handlers<br/>[handlers.py]"]
  node_stream_consumer["Stream consumer groups<br/>[stream_listner.py]"]
  node_pubsub["Pub/Sub subscribers<br/>[subscribers.py]"]
  node_outbox["Transactional outbox<br/>[outbox_service.py]"]
end

subgraph group_state["Persistence and state"]
  node_redis[("Redis state and streams<br/>[redis_client.py]")]
  node_presence["Presence cache<br/>[presence.py]"]
  node_conv_cache["Conversation cache<br/>[conversation.py]"]
  node_postgres[("PostgreSQL application state<br/>[database.py]")]
end

subgraph group_notifications["Profiles and notifications"]
  node_profile_routes["Profile and settings routes<br/>[profile.py]"]
  node_notifications["Notification service"]
end

node_user(("Chat user"))
node_push["Web Push provider"]

node_user -->|"uses API"| node_app
node_app -->|"registers routes"| node_auth_routes
node_auth_routes -->|"looks up users"| node_identity
node_auth_routes -->|"issues tokens"| node_jwt
node_auth_routes -->|"creates user"| node_users_model
node_user -->|"manages conversations"| node_chat_routes
node_chat_routes -->|"uses membership cache"| node_conv_cache
node_user -->|"sends messages"| node_message_routes
node_message_routes -->|"processes messages"| node_chat_service
node_message_routes -->|"reads and writes"| node_chat_models
node_user -->|"connects by WebSocket"| node_ws_socket
node_ws_socket -->|"manages connections"| node_ws_manager
node_ws_manager -->|"tracks connections"| node_redis
node_ws_manager -->|"updates presence"| node_presence
node_chat_service -.->|"records persistent events"| node_outbox
node_outbox -->|"reads pending events"| node_postgres
node_outbox -->|"publishes stream events"| node_redis
node_redis -->|"delivers stream events"| node_stream_consumer
node_stream_consumer -->|"dispatches events"| node_redis_handlers
node_redis_handlers -->|"fans out events"| node_ws_manager
node_user -->|"sends transient events"| node_pubsub
node_pubsub -.->|"subscribes to Pub/Sub"| node_redis
node_app -->|"registers routes"| node_profile_routes
node_user -->|"receives notifications"| node_notifications
node_notifications -->|"dispatches Web Push"| node_push
node_notifications -->|"publishes notification events"| node_redis
node_user -->|"uploads attachments"| node_storage
node_app -->|"mounts admin"| node_admin
node_chat_routes -.->|"persists conversations"| node_postgres
node_ws_socket -->|"handles message events"| node_chat_service

click node_app "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/main.py"
click node_auth_routes "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/auth.py"
click node_identity "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/user.py"
click node_jwt "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/core/security/auth.py"
click node_chat_routes "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/chat.py"
click node_message_routes "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/messages.py"
click node_chat_service "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/messages.py"
click node_ws_socket "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/ws/sockets.py"
click node_ws_manager "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/ws/manager.py"
click node_redis_handlers "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis/handlers.py"
click node_stream_consumer "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis/stream_listner.py"
click node_pubsub "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis/subscribers.py"
click node_outbox "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/outbox_service.py"
click node_redis "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis_client.py"
click node_presence "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/cache_management/presence.py"
click node_conv_cache "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/cache_management/conversation.py"
click node_postgres "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/database.py"
click node_chat_models "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/models/chat/messages.py"
click node_users_model "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/models/auth/user.py"
click node_profile_routes "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/profile.py"
click node_notifications "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/notification_service.py"
click node_storage "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/storage_service.py"
click node_admin "https://github.com/sadhguru-slayer/fieldchat/blob/main/app/admin/message.py"

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_app,node_auth_routes,node_identity,node_jwt,node_users_model,node_admin,node_user toneBlue
class node_chat_routes,node_message_routes,node_chat_service,node_chat_models,node_storage toneAmber
class node_ws_socket,node_ws_manager,node_redis_handlers,node_stream_consumer,node_pubsub,node_outbox toneMint
class node_redis,node_presence,node_conv_cache,node_postgres toneRose
class node_profile_routes,node_notifications,node_push toneIndigo
```

## Components

### API and identity

- [FastAPI application](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/main.py): `app/main.py`
- [Authentication routes](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/auth.py): `app/router/auth.py`
- [User and token services](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/user.py): `app/services/user.py`
- [JWT security](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/core/security/auth.py): `app/core/security/auth.py`
- [User model](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/models/auth/user.py): `app/models/auth/user.py`
- [Admin operations](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/admin/message.py): `app/admin/message.py`

### Chat domain

- [Conversation routes](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/chat.py): `app/router/chat.py`
- [Message routes](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/messages.py): `app/router/messages.py`
- [Message processing](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/messages.py): `app/services/messages.py`
- [Messages and chat models](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/models/chat/messages.py): `app/models/chat/messages.py`
- [Attachment storage](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/storage_service.py): `app/services/storage_service.py`

### Realtime delivery

- [WebSocket event handling](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/ws/sockets.py): `app/ws/sockets.py`
- [Connection manager](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/ws/manager.py): `app/ws/manager.py`
- [Redis event handlers](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis/handlers.py): `app/redis/handlers.py`
- [Stream consumer groups](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis/stream_listner.py): `app/redis/stream_listner.py`
- [Pub/Sub subscribers](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis/subscribers.py): `app/redis/subscribers.py`
- [Transactional outbox](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/outbox_service.py): `app/services/outbox_service.py`

### Persistence and state

- [Redis state and streams](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/redis_client.py): `app/redis_client.py`
- [Presence cache](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/cache_management/presence.py): `app/services/cache_management/presence.py`
- [Conversation cache](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/cache_management/conversation.py): `app/services/cache_management/conversation.py`
- [PostgreSQL application state](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/database.py): `app/database.py`

### Profiles and notifications

- [Profile and settings routes](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/router/profile.py): `app/router/profile.py`
- [Notification service](https://github.com/sadhguru-slayer/fieldchat/blob/main/app/services/notification_service.py): `app/services/notification_service.py`

### Other components

- **Chat user**
- **Web Push provider**

## Connections

- Chat user → FastAPI application: uses API
- FastAPI application → Authentication routes: registers routes (evidence: `app/main.py`)
- Authentication routes → User and token services: looks up users (evidence: `app/router/auth.py`)
- Authentication routes → JWT security: issues tokens (evidence: `app/router/auth.py`)
- Authentication routes → User model: creates user (evidence: `app/router/auth.py`)
- Chat user → Conversation routes: manages conversations
- Conversation routes → Conversation cache: uses membership cache (evidence: `app/router/chat.py`)
- Chat user → Message routes: sends messages
- Message routes → Message processing: processes messages (evidence: `app/router/messages.py`)
- Message routes → Messages and chat models: reads and writes (evidence: `app/router/messages.py`)
- Chat user → WebSocket event handling: connects by WebSocket
- WebSocket event handling → Connection manager: manages connections (evidence: `app/ws/sockets.py`)
- Connection manager → Redis state and streams: tracks connections (evidence: `app/ws/manager.py`)
- Connection manager → Presence cache: updates presence (evidence: `app/ws/manager.py`)
- Message processing → Transactional outbox: records persistent events
- Transactional outbox → PostgreSQL application state: reads pending events (evidence: `app/services/outbox_service.py`)
- Transactional outbox → Redis state and streams: publishes stream events (evidence: `app/services/outbox_service.py`)
- Redis state and streams → Stream consumer groups: delivers stream events (evidence: `app/redis/stream_listner.py`)
- Stream consumer groups → Redis event handlers: dispatches events (evidence: `app/redis/stream_listner.py`)
- Redis event handlers → Connection manager: fans out events (evidence: `app/redis/handlers.py`)
- Chat user → Pub/Sub subscribers: sends transient events
- Pub/Sub subscribers → Redis state and streams: subscribes to Pub/Sub
- FastAPI application → Profile and settings routes: registers routes (evidence: `app/main.py`)
- Chat user → Notification service: receives notifications
- Notification service → Web Push provider: dispatches Web Push (evidence: `app/services/notification_service.py`)
- Notification service → Redis state and streams: publishes notification events (evidence: `app/services/notification_service.py`)
- Chat user → Attachment storage: uploads attachments
- FastAPI application → Admin operations: mounts admin (evidence: `app/main.py`)
- Conversation routes → PostgreSQL application state: persists conversations
- WebSocket event handling → Message processing: handles message events (evidence: `app/ws/sockets.py`)
