# harshs490/pulsechat-backend architecture

> Architecture diagram of the GitHub repository harshs490/pulsechat-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshs490/pulsechat-backend
- Repository: https://github.com/harshs490/pulsechat-backend

## Overview

##### Project’s type and purpose
- This is a backend-focused, real-time chat service built on Express.js and TypeScript.
- It exposes REST endpoints (auth, users, friends, conversations) and a WebSocket interface for real-time messaging.
- It uses Prisma to manage a relational database, Kafka for event streaming, and Redis for caching or pub/sub.

##### File structure
Top-level files
- package.json / package-lock.json – Node dependencies.
- tsconfig.json – TypeScript compiler settings.
- .gitignore, ca.pem – git and certificates.
prisma/
- schema.prisma – data model.
- migrations/ – SQL migrations tracking chat, users, messages, indexing.
src/
- config/ – kafka.ts, prisma.ts, redis.config.ts (connectors for external services).
- controllers/ – business logic for auth, users, friends, conversations.
- middlewares/ – AuthMiddleware to protect routes.
- models/ – input/output schemas.
- routes/ – routes.ts binds controllers to URLs.
- socket.ts – WebSocket server setup for real-time events.
- index.ts – application entrypoint (HTTP server and WebSocket attachment).

##### README
- Describes it as an “Express JS With Typescript Starter KIT” meant to run at localhost:8000.

##### Main components
1. Clients
– Browser or mobile client (REST + WebSocket).
2. API Layer (Express.js)
– HTTP server (index.ts)
– Routes → Controllers → Services
– AuthMiddleware enforces security
3. WebSocket Layer
– socket.ts manages real-time connections
– Emits and listens for chat events
4. Business Logic
– Controllers handle requests and events
– Models/schemas validate payloads
5. Data Persistence
– Prisma Client (prisma.ts)
– PostgreSQL (or other SQL) behind prisma/schema.prisma
6. Messaging & Caching
– Kafka cluster (kafka.ts) for event streaming (e.g., message queuing, notifications)
– Redis (redis.config.ts) for caching session data, pub/sub
7. Migrations
– prisma/migrations track schema changes

##### Relationships and interactions
- Client → HTTP endpoints → Express router → Controller → Prisma → Database
- Client → WebSocket → socket.ts → Controller → Kafka (publish/subscribe)
- Controllers or socket handlers → Redis for caching or to coordinate pub/sub
- Kafka consumers (could be separate workers) → process events → write back to DB or emit to WebSocket clients

##### Architectural patterns and design principles
- Layered architecture: Presentation (Routes/Socket), Business (Controllers), Data (Prisma/DB)
- Single service approach (monolith) with event-driven elements (Kafka)
- Use of middleware for cross-cutting concerns (authentication)
- Schema-first data modeling via Prisma

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Client["Client (Browser/Mobile)"]:::client

    %% Backend Service
    subgraph "Backend Service"
        direction TB
        HTTP["Express HTTP Server"]:::api
        WS["WebSocket Server"]:::api
        Routes["HTTP Routing"]:::api
        AuthMW["Auth Middleware"]:::api
        subgraph "Controllers"
            direction TB
            AuthCtrl["Auth Controller"]:::api
            UsersCtrl["Users Controller"]:::api
            FriendsCtrl["Friends Controller"]:::api
            ConvCtrl["Conversations Controller"]:::api
        end
        Schemas["Models/Schemas"]:::api
        PrismaClient["Prisma Client"]:::datastore
    end

    %% External Services
    Postgres["PostgreSQL"]:::datastore
    PrismaSchema["Prisma Schema"]:::datastore
    Migrations["Prisma Migrations"]:::datastore
    Kafka["Kafka"]:::messaging
    Redis["Redis"]:::messaging
    Worker["Kafka Consumer Worker"]:::messaging

    %% Connections
    Client -->|"HTTP (port 8000)"| HTTP
    Client -->|"WS (port 8000/ws)"| WS
    HTTP -->|routes| Routes
    Routes -->|uses| AuthMW
    Routes -->|calls| AuthCtrl
    Routes -->|calls| UsersCtrl
    Routes -->|calls| FriendsCtrl
    Routes -->|calls| ConvCtrl
    WS -->|events| ConvCtrl
    AuthCtrl -->|validates| Schemas
    UsersCtrl -->|validates| Schemas
    FriendsCtrl -->|validates| Schemas
    ConvCtrl -->|validates| Schemas
    AuthCtrl -->|DB queries| PrismaClient
    UsersCtrl -->|DB queries| PrismaClient
    FriendsCtrl -->|DB queries| PrismaClient
    ConvCtrl -->|DB queries| PrismaClient
    PrismaClient -->|SQL| Postgres
    PrismaSchema --> Postgres
    Migrations --> Postgres
    ConvCtrl -->|publish| Kafka
    Worker -->|consume| Kafka
    Worker -->|DB write| PrismaClient
    ConvCtrl -->|cache/pubsub| Redis
    AuthCtrl -->|cache| Redis

    %% Click Events
    click HTTP "https://github.com/harshs490/pulsechat-backend/blob/main/src/index.ts"
    click Routes "https://github.com/harshs490/pulsechat-backend/blob/main/src/routes/routes.ts"
    click AuthMW "https://github.com/harshs490/pulsechat-backend/blob/main/src/middlewares/AuthMiddleware.ts"
    click AuthCtrl "https://github.com/harshs490/pulsechat-backend/blob/main/src/controllers/auth.controller.ts"
    click UsersCtrl "https://github.com/harshs490/pulsechat-backend/blob/main/src/controllers/users.controller.ts"
    click FriendsCtrl "https://github.com/harshs490/pulsechat-backend/blob/main/src/controllers/friends.controller.ts"
    click ConvCtrl "https://github.com/harshs490/pulsechat-backend/blob/main/src/controllers/conversation.controller.ts"
    click WS "https://github.com/harshs490/pulsechat-backend/blob/main/src/socket.ts"
    click Schemas "https://github.com/harshs490/pulsechat-backend/blob/main/src/models/auth.schemas.ts"
    click PrismaClient "https://github.com/harshs490/pulsechat-backend/blob/main/src/config/prisma.ts"
    click PrismaSchema "https://github.com/harshs490/pulsechat-backend/blob/main/prisma/schema.prisma"
    click Migrations "https://github.com/harshs490/pulsechat-backend/tree/main/prisma/migrations/"

    %% Styles
    classDef client fill:#e0c3fc,stroke:#a55bcb;
    classDef api fill:#c3dafe,stroke:#4a69bb;
    classDef datastore fill:#ffd9b3,stroke:#d18b1f;
    classDef messaging fill:#c3fcd3,stroke:#2d8f2d;
```
