# jangirdnick/perpx architecture

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

- Interactive diagram: https://gitdiagram.com/jangirdnick/perpx
- Repository: https://github.com/jangirdnick/perpx

## Overview

PERPX is a research-and-collaboration chat platform. A user signs in, starts a personal or space chat, and sends a message; the API handles real-time chat and AI research responses, while the client displays streamed messages and maintains chat history. Users can also manage spaces, upload files for image attachments or document RAG, and manage their account. The README documents AI providers and integrations; some connections to those integrations are therefore documented rather than verified from sampled implementation. The API service layer and storage adapters are shown separately.

Main entry points: [`apps/api/src/auth/auth.service.ts`](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/auth/auth.service.ts) (Auth service), [`apps/web/src/app/(dashboard)/page.tsx`](https://github.com/jangirdnick/perpx/blob/main/apps/web/src/app/(dashboard)/page.tsx) (Web experience), [`apps/web/src/modules/chat/hooks/useChat.ts`](https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/chat/hooks/useChat.ts) (Chat state and stream), [`apps/web/src/modules/chat/hooks/useSpaceChat.ts`](https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/chat/hooks/useSpaceChat.ts) (Space chat state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["Web experience<br/>[page.tsx]"]
  node_authui["Auth flows<br/>[useAuth.ts]"]
  node_chatui["Chat state and stream<br/>[useChat.ts]"]
  node_spaceui["Space chat state<br/>[useSpaceChat.ts]"]
  node_shared["Shared API types<br/>[api.type.ts]"]
end

subgraph group_identity["Identity and profiles"]
  node_authcontroller["Auth endpoints<br/>[auth.controller.ts]"]
  node_authservice["Auth service<br/>[auth.service.ts]"]
  node_authguard["JWT auth guard<br/>[auth.guard.ts]"]
  node_users["User profiles<br/>[user.service.ts]"]
  node_email["Verification email<br/>[email.service.ts]"]
end

subgraph group_conversation["Chat and AI"]
  node_chatcontroller["Chat endpoints<br/>[chat.controller.ts]"]
  node_chatservice["Chat service<br/>[chat.service.ts]"]
  node_gateway["Realtime gateway<br/>[chat.gateway.ts]"]
  node_ai["AI research service<br/>[api.service.ts]"]
  node_messages["Message history<br/>[message.service.ts]"]
end

subgraph group_collaboration["Spaces and files"]
  node_spaces["Space management<br/>[space.service.ts]"]
  node_upload["File uploads<br/>[upload.service.ts]"]
end

subgraph group_platform["Data and integrations"]
  node_postgres[("PostgreSQL<br/>[prisma.service.ts]")]
  node_redis[("Redis cache<br/>[redis.service.ts]")]
  node_vector["Vector retrieval<br/>[vector.service.ts]"]
  node_models{{"AI model providers"}}
  node_search{{"Web search"}}
  node_s3[("AWS S3")]
  node_resend{{"Resend"}}
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -->|"signs in"| node_authui
node_webapp -->|"starts chat"| node_chatui
node_webapp -->|"uses spaces"| node_spaceui
node_authui -->|"HTTP requests"| node_authcontroller
node_chatui -->|"HTTP requests"| node_chatcontroller
node_spaceui -->|"HTTP requests"| node_chatcontroller
node_chatui -->|"WebSocket events"| node_gateway
node_spaceui -->|"WebSocket events"| node_gateway
node_authcontroller -->|"delegates"| node_authservice
node_authservice -->|"uses"| node_users
node_authservice -->|"sends verification"| node_email
node_authservice -->|"reads and writes"| node_postgres
node_authservice -.->|"sends email"| node_resend
node_chatcontroller -->|"guards routes"| node_authguard
node_chatcontroller -->|"delegates"| node_chatservice
node_chatservice -->|"persists chats"| node_postgres
node_gateway -.->|"dispatches prompts"| node_ai
node_gateway -.->|"persists messages"| node_messages
node_ai -->|"generates responses"| node_models
node_ai -->|"augments research"| node_search
node_ai -.->|"retrieves documents"| node_vector
node_vector -->|"embeddings"| node_models
node_chatui -->|"uses response types"| node_shared
node_spaceui -->|"uses response types"| node_shared
node_spaces -.->|"stores spaces"| node_postgres
node_upload -->|"uploads files"| node_s3
node_authguard -->|"reads and caches users"| node_redis
node_authguard -->|"loads user"| node_postgres

click node_webapp "https://github.com/jangirdnick/perpx/blob/main/apps/web/src/app/(dashboard)/page.tsx"
click node_authui "https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/auth/hooks/useAuth.ts"
click node_chatui "https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/chat/hooks/useChat.ts"
click node_spaceui "https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/chat/hooks/useSpaceChat.ts"
click node_shared "https://github.com/jangirdnick/perpx/blob/main/packages/shared/types/api.type.ts"
click node_authcontroller "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/auth/auth.controller.ts"
click node_authservice "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/auth/auth.service.ts"
click node_authguard "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/auth/guards/auth.guard.ts"
click node_users "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/user/user.service.ts"
click node_chatcontroller "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/chat/chat.controller.ts"
click node_chatservice "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/chat/chat.service.ts"
click node_gateway "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/chat/chat/chat.gateway.ts"
click node_ai "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/api/api.service.ts"
click node_messages "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/message/message.service.ts"
click node_spaces "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/space/space.service.ts"
click node_upload "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/upload/upload.service.ts"
click node_email "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/email/email.service.ts"
click node_postgres "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/prisma/prisma.service.ts"
click node_redis "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/redis/redis.service.ts"
click node_vector "https://github.com/jangirdnick/perpx/blob/main/apps/api/src/vector/vector.service.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_authui,node_chatui,node_spaceui,node_shared,node_user toneBlue
class node_authcontroller,node_authservice,node_authguard,node_users,node_email toneAmber
class node_chatcontroller,node_chatservice,node_gateway,node_ai,node_messages toneMint
class node_spaces,node_upload toneRose
class node_postgres,node_redis,node_vector,node_models,node_search,node_s3,node_resend toneIndigo
```

## Components

### Web client

- [Web experience](https://github.com/jangirdnick/perpx/blob/main/apps/web/src/app/(dashboard)/page.tsx): `apps/web/src/app/(dashboard)/page.tsx`
- [Auth flows](https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/auth/hooks/useAuth.ts): `apps/web/src/modules/auth/hooks/useAuth.ts`
- [Chat state and stream](https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/chat/hooks/useChat.ts): `apps/web/src/modules/chat/hooks/useChat.ts`
- [Space chat state](https://github.com/jangirdnick/perpx/blob/main/apps/web/src/modules/chat/hooks/useSpaceChat.ts): `apps/web/src/modules/chat/hooks/useSpaceChat.ts`
- [Shared API types](https://github.com/jangirdnick/perpx/blob/main/packages/shared/types/api.type.ts): `packages/shared/types/api.type.ts`

### Identity and profiles

- [Auth endpoints](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/auth/auth.controller.ts): `apps/api/src/auth/auth.controller.ts`
- [Auth service](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/auth/auth.service.ts): `apps/api/src/auth/auth.service.ts`
- [JWT auth guard](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/auth/guards/auth.guard.ts): `apps/api/src/auth/guards/auth.guard.ts`
- [User profiles](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/user/user.service.ts): `apps/api/src/user/user.service.ts`
- [Verification email](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/email/email.service.ts): `apps/api/src/email/email.service.ts`

### Chat and AI

- [Chat endpoints](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/chat/chat.controller.ts): `apps/api/src/chat/chat.controller.ts`
- [Chat service](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/chat/chat.service.ts): `apps/api/src/chat/chat.service.ts`
- [Realtime gateway](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/chat/chat/chat.gateway.ts): `apps/api/src/chat/chat/chat.gateway.ts`
- [AI research service](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/api/api.service.ts): `apps/api/src/api/api.service.ts`
- [Message history](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/message/message.service.ts): `apps/api/src/message/message.service.ts`

### Spaces and files

- [Space management](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/space/space.service.ts): `apps/api/src/space/space.service.ts`
- [File uploads](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/upload/upload.service.ts): `apps/api/src/upload/upload.service.ts`

### Data and integrations

- [PostgreSQL](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/prisma/prisma.service.ts): `apps/api/src/prisma/prisma.service.ts`
- [Redis cache](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/redis/redis.service.ts): `apps/api/src/redis/redis.service.ts`
- [Vector retrieval](https://github.com/jangirdnick/perpx/blob/main/apps/api/src/vector/vector.service.ts): `apps/api/src/vector/vector.service.ts`
- **AI model providers**
- **Web search**
- **AWS S3**
- **Resend**

### Other components

- **User**

## Connections

- User → Web experience: uses
- Web experience → Auth flows: signs in
- Web experience → Chat state and stream: starts chat
- Web experience → Space chat state: uses spaces
- Auth flows → Auth endpoints: HTTP requests
- Chat state and stream → Chat endpoints: HTTP requests
- Space chat state → Chat endpoints: HTTP requests
- Chat state and stream → Realtime gateway: WebSocket events
- Space chat state → Realtime gateway: WebSocket events
- Auth endpoints → Auth service: delegates (evidence: `apps/api/src/auth/auth.controller.ts`)
- Auth service → User profiles: uses (evidence: `apps/api/src/auth/auth.service.ts`)
- Auth service → Verification email: sends verification (evidence: `apps/api/src/auth/auth.service.ts`)
- Auth service → PostgreSQL: reads and writes (evidence: `apps/api/src/auth/auth.service.ts`)
- Auth service → Resend: sends email
- Chat endpoints → JWT auth guard: guards routes (evidence: `apps/api/src/chat/chat.controller.ts`)
- Chat endpoints → Chat service: delegates (evidence: `apps/api/src/chat/chat.controller.ts`)
- Chat service → PostgreSQL: persists chats (evidence: `apps/api/src/chat/chat.service.ts`)
- Realtime gateway → AI research service: dispatches prompts
- Realtime gateway → Message history: persists messages
- AI research service → AI model providers: generates responses
- AI research service → Web search: augments research
- AI research service → Vector retrieval: retrieves documents
- Vector retrieval → AI model providers: embeddings
- Chat state and stream → Shared API types: uses response types (evidence: `apps/web/src/modules/chat/hooks/useChat.ts`)
- Space chat state → Shared API types: uses response types (evidence: `apps/web/src/modules/chat/hooks/useSpaceChat.ts`)
- Space management → PostgreSQL: stores spaces
- File uploads → AWS S3: uploads files
- JWT auth guard → Redis cache: reads and caches users (evidence: `apps/api/src/auth/guards/auth.guard.ts`)
- JWT auth guard → PostgreSQL: loads user (evidence: `apps/api/src/auth/guards/auth.guard.ts`)
