# gilsngprmns/signal-ai-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/gilsngprmns/signal-ai-assistant
- Repository: https://github.com/gilsngprmns/signal-ai-assistant

## Overview

Signal AI is a conversational assistant whose primary flow is a user sending a mode-specific message, receiving a Gemini response, and retaining the conversation in PostgreSQL. The React app also provides authentication, conversation history, and admin tools. Document upload and retrieval modules remain in the repository, but the README says they are dormant for normal chat. The graph follows documented and indexed connections; unsampled subsystems are represented conservatively, and the legacy retrieval branch is marked optional.

Main entry points: [`frontend/src/App.jsx`](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/App.jsx) (React app), [`backend/src/app.js`](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/app.js) (Express API), [`backend/src/services/chat.service.js`](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/chat.service.js) (Chat orchestration), [`backend/src/services/rag.service.js`](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/rag.service.js) (Document retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React application"]
  node_webapp["React app<br/>[App.jsx]"]
  node_chatui["Chat interface<br/>[Chat.jsx]"]
  node_authui["Auth state and pages<br/>[AuthContext.jsx]"]
  node_historyui["Conversation history<br/>[History.jsx]"]
  node_adminui["Admin console<br/>[AdminDashboard.jsx]"]
  node_frontendservices["Frontend API services<br/>[api.js]"]
end

subgraph group_api["API and identity"]
  node_express["Express API<br/>[app.js]"]
  node_authroutes["Auth routes and guards<br/>[auth.routes.js]"]
  node_authcontroller["Auth controller<br/>[auth.controller.js]"]
  node_authservice["Auth service<br/>[auth.service.js]"]
end

subgraph group_chat["Conversation and AI"]
  node_conversationroutes["Conversation routes"]
  node_chatcontroller["Chat controller<br/>[chat.controller.js]"]
  node_chatservice["Chat orchestration<br/>[chat.service.js]"]
  node_conversationstore["Conversation storage"]
  node_contextstore["AI settings and contexts"]
  node_aiservice["Gemini generation<br/>[ai.service.js]"]
end

subgraph group_admin["Administration"]
  node_adminroutes["Admin routes<br/>[admin.routes.js]"]
  node_admincontroller["Admin controller"]
  node_adminservice["Admin services<br/>[admin.service.js]"]
  node_adminrepo["Admin data access"]
end

subgraph group_legacy["Legacy documents"]
  node_documentui["Document interface<br/>[UploadDocument.jsx]"]
  node_documentcontroller["Document controller"]
  node_rag["Document retrieval<br/>[rag.service.js]"]
  node_embedding["Embedding generation"]
  node_documentstore["Document and chunk storage"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]
node_gemini["Gemini"]

node_user -->|"uses"| node_webapp
node_webapp -->|"calls API"| node_express
node_webapp -->|"routes to"| node_chatui
node_webapp -->|"provides auth"| node_authui
node_webapp -->|"routes to"| node_historyui
node_webapp -->|"routes to"| node_adminui
node_chatui -->|"uses"| node_frontendservices
node_authui -->|"uses"| node_frontendservices
node_frontendservices -->|"sends requests"| node_express
node_express -->|"mounts"| node_authroutes
node_express -->|"mounts"| node_conversationroutes
node_express -->|"mounts"| node_adminroutes
node_authroutes -->|"routes to"| node_authcontroller
node_authcontroller -->|"delegates to"| node_authservice
node_conversationroutes -->|"routes messages"| node_chatcontroller
node_chatcontroller -->|"requests response"| node_chatservice
node_chatservice -->|"reads and writes"| node_conversationstore
node_chatservice -->|"loads context"| node_contextstore
node_chatservice -->|"requests generation"| node_aiservice
node_conversationstore -->|"queries"| node_postgres
node_contextstore -->|"queries"| node_postgres
node_aiservice -->|"generates replies"| node_gemini
node_adminroutes -->|"routes to"| node_admincontroller
node_admincontroller -->|"delegates to"| node_adminservice
node_adminservice -.->|"uses data access"| node_adminrepo
node_adminrepo -->|"queries"| node_postgres
node_documentui -.->|"uploads to"| node_documentcontroller
node_documentcontroller -.->|"may invoke"| node_rag
node_rag -->|"embeds query"| node_embedding
node_rag -->|"checks and searches"| node_documentstore
node_embedding -->|"requests embeddings"| node_gemini

click node_webapp "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/App.jsx"
click node_chatui "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/pages/Chat.jsx"
click node_authui "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/context/AuthContext.jsx"
click node_historyui "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/pages/History.jsx"
click node_adminui "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/pages/admin/AdminDashboard.jsx"
click node_frontendservices "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/services/api.js"
click node_express "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/app.js"
click node_authroutes "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/routes/auth.routes.js"
click node_authcontroller "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/auth.controller.js"
click node_authservice "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/auth.service.js"
click node_conversationroutes "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/routes/conversation.routes.js"
click node_chatcontroller "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/chat.controller.js"
click node_chatservice "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/chat.service.js"
click node_conversationstore "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/conversation.repository.js"
click node_contextstore "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/context.repository.js"
click node_aiservice "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/ai.service.js"
click node_adminroutes "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/routes/admin.routes.js"
click node_admincontroller "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/admin.controller.js"
click node_adminservice "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/admin.service.js"
click node_adminrepo "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/admin.repository.js"
click node_documentui "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/components/UploadDocument.jsx"
click node_documentcontroller "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/document.controller.js"
click node_rag "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/rag.service.js"
click node_embedding "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/embedding.service.js"
click node_documentstore "https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/document.repository.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_webapp,node_chatui,node_authui,node_historyui,node_adminui,node_frontendservices,node_user toneBlue
class node_express,node_authroutes,node_authcontroller,node_authservice,node_postgres toneAmber
class node_conversationroutes,node_chatcontroller,node_chatservice,node_conversationstore,node_contextstore,node_aiservice toneMint
class node_adminroutes,node_admincontroller,node_adminservice,node_adminrepo toneRose
class node_documentui,node_documentcontroller,node_rag,node_embedding,node_documentstore,node_gemini toneIndigo
```

## Components

### React application

- [React app](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Chat interface](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/pages/Chat.jsx): `frontend/src/pages/Chat.jsx`
- [Auth state and pages](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/context/AuthContext.jsx): `frontend/src/context/AuthContext.jsx`
- [Conversation history](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/pages/History.jsx): `frontend/src/pages/History.jsx`
- [Admin console](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/pages/admin/AdminDashboard.jsx): `frontend/src/pages/admin/AdminDashboard.jsx`
- [Frontend API services](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### API and identity

- [Express API](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/app.js): `backend/src/app.js`
- [Auth routes and guards](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`
- [Auth controller](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/auth.controller.js): `backend/src/controllers/auth.controller.js`
- [Auth service](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/auth.service.js): `backend/src/services/auth.service.js`

### Conversation and AI

- [Conversation routes](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/routes/conversation.routes.js): `backend/src/routes/conversation.routes.js`
- [Chat controller](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/chat.controller.js): `backend/src/controllers/chat.controller.js`
- [Chat orchestration](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/chat.service.js): `backend/src/services/chat.service.js`
- [Conversation storage](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/conversation.repository.js): `backend/src/repositories/conversation.repository.js`
- [AI settings and contexts](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/context.repository.js): `backend/src/repositories/context.repository.js`
- [Gemini generation](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/ai.service.js): `backend/src/services/ai.service.js`

### Administration

- [Admin routes](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/routes/admin.routes.js): `backend/src/routes/admin.routes.js`
- [Admin controller](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/admin.controller.js): `backend/src/controllers/admin.controller.js`
- [Admin services](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/admin.service.js): `backend/src/services/admin.service.js`
- [Admin data access](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/admin.repository.js): `backend/src/repositories/admin.repository.js`

### Legacy documents

- [Document interface](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/frontend/src/components/UploadDocument.jsx): `frontend/src/components/UploadDocument.jsx`
- [Document controller](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/controllers/document.controller.js): `backend/src/controllers/document.controller.js`
- [Document retrieval](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/rag.service.js): `backend/src/services/rag.service.js`
- [Embedding generation](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/services/embedding.service.js): `backend/src/services/embedding.service.js`
- [Document and chunk storage](https://github.com/gilsngprmns/signal-ai-assistant/blob/main/backend/src/repositories/document.repository.js): `backend/src/repositories/document.repository.js`

### Other components

- **User**
- **PostgreSQL**
- **Gemini**

## Connections

- User → React app: uses (evidence: `README.md`)
- React app → Express API: calls API (evidence: `README.md`)
- React app → Chat interface: routes to (evidence: `frontend/src/App.jsx`)
- React app → Auth state and pages: provides auth (evidence: `frontend/src/App.jsx`)
- React app → Conversation history: routes to (evidence: `frontend/src/App.jsx`)
- React app → Admin console: routes to (evidence: `frontend/src/App.jsx`)
- Chat interface → Frontend API services: uses (evidence: `frontend/src/pages/Chat.jsx`)
- Auth state and pages → Frontend API services: uses (evidence: `frontend/src/context/AuthContext.jsx`)
- Frontend API services → Express API: sends requests (evidence: `README.md`)
- Express API → Auth routes and guards: mounts (evidence: `backend/src/app.js`)
- Express API → Conversation routes: mounts (evidence: `backend/src/app.js`)
- Express API → Admin routes: mounts (evidence: `backend/src/app.js`)
- Auth routes and guards → Auth controller: routes to (evidence: `backend/src/routes/auth.routes.js`)
- Auth controller → Auth service: delegates to (evidence: `backend/src/controllers/auth.controller.js`)
- Conversation routes → Chat controller: routes messages (evidence: `backend/src/routes/conversation.routes.js`)
- Chat controller → Chat orchestration: requests response (evidence: `backend/src/controllers/chat.controller.js`)
- Chat orchestration → Conversation storage: reads and writes (evidence: `backend/src/services/chat.service.js`)
- Chat orchestration → AI settings and contexts: loads context (evidence: `backend/src/services/chat.service.js`)
- Chat orchestration → Gemini generation: requests generation (evidence: `backend/src/services/chat.service.js`)
- Conversation storage → PostgreSQL: queries (evidence: `backend/src/repositories/conversation.repository.js`)
- AI settings and contexts → PostgreSQL: queries (evidence: `backend/src/repositories/context.repository.js`)
- Gemini generation → Gemini: generates replies (evidence: `README.md`)
- Admin routes → Admin controller: routes to (evidence: `backend/src/routes/admin.routes.js`)
- Admin controller → Admin services: delegates to (evidence: `backend/src/controllers/admin.controller.js`)
- Admin services → Admin data access: uses data access
- Admin data access → PostgreSQL: queries (evidence: `backend/src/repositories/admin.repository.js`)
- Document interface → Document controller: uploads to
- Document controller → Document retrieval: may invoke
- Document retrieval → Embedding generation: embeds query (evidence: `backend/src/services/rag.service.js`)
- Document retrieval → Document and chunk storage: checks and searches (evidence: `backend/src/services/rag.service.js`)
- Embedding generation → Gemini: requests embeddings (evidence: `backend/src/services/embedding.service.js`)