# akhmadov-360/helix architecture

> Architecture diagram of the GitHub repository akhmadov-360/helix, 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/akhmadov-360/helix
- Repository: https://github.com/akhmadov-360/helix

## Overview

Helix is an AI-native, project-based CRM: users manage leads as project workspaces with pipeline phases, contacts, tasks, pages, files, knowledge articles, and activity, then ask a project-scoped RAG assistant about that context. The web app routes user actions through feature views and shared API transport to the NestJS service layer; services own domain operations and data access. Authentication and organization-scoped authorization protect those operations. README documents queued email, embedding, and maintenance work. The graph reflects those documented capabilities; the sampled source excerpts confirm selected controller, session, storage, and embedding behavior, not every subsystem’s wiring.

Main entry points: [`apps/web/src/shared/api/client.ts`](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/shared/api/client.ts) (API transport), [`apps/api/src/modules/ai/ingest-embeddings.worker.ts`](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/ai/ingest-embeddings.worker.ts) (Embedding ingestion), [`packages/db/src/index.ts`](https://github.com/akhmadov-360/helix/blob/main/packages/db/src/index.ts) (PostgreSQL and pgvector), [`apps/web/src/features/project-detail/project-detail-shell.tsx`](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/project-detail/project-detail-shell.tsx) (Project workspace UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_routes["Routes and shell<br/>[index.tsx]"]
  node_board["Pipeline board<br/>[board-view.tsx]"]
  node_project_ui["Project workspace UI"]
  node_content_ui["Pages and files UI"]
  node_chat_ui["AI chat UI<br/>[chat-drawer.tsx]"]
  node_transport["API transport<br/>[client.ts]"]
end

subgraph group_identity["Identity and access"]
  node_auth_api["Authentication API<br/>[auth.controller.ts]"]
  node_sessions["Refresh sessions"]
  node_org_api["Organization management"]
end

subgraph group_crm["CRM workflow"]
  node_projects_api["Projects and board"]
  node_tasks_api["Tasks"]
  node_crm_api["Companies and contacts"]
  node_workspace_service["Workspace services"]
end

subgraph group_content_ai["Workspace content and AI"]
  node_pages_api["Pages and history"]
  node_attachments_api["Project attachments"]
  node_kb_api["Knowledge base<br/>[kb.controller.ts]"]
  node_ai_threads["RAG chat service"]
  node_ingest["Embedding ingestion"]
  node_chunk_repo["Vector chunks"]
end

subgraph group_runtime["Runtime infrastructure"]
  node_database[("PostgreSQL and pgvector<br/>[index.ts]")]
  node_queue["Redis job queues<br/>[queue.module.ts]"]
  node_object_store["S3-compatible storage<br/>[s3.service.ts]"]
  node_ai_provider["AI provider adapters"]
  node_mail["Email delivery"]
end

node_user(("CRM user"))

node_user -->|"uses"| node_routes
node_routes -->|"opens"| node_board
node_routes -->|"opens"| node_project_ui
node_project_ui -->|"opens"| node_content_ui
node_project_ui -->|"opens"| node_chat_ui
node_board -->|"requests"| node_transport
node_project_ui -->|"requests"| node_transport
node_content_ui -->|"requests"| node_transport
node_chat_ui -->|"streams"| node_transport
node_transport -->|"calls"| node_auth_api
node_transport -->|"calls"| node_projects_api
node_transport -->|"calls"| node_tasks_api
node_transport -->|"calls"| node_crm_api
node_transport -->|"calls"| node_pages_api
node_transport -->|"calls"| node_attachments_api
node_transport -->|"calls"| node_kb_api
node_transport -->|"calls"| node_ai_threads
node_transport -->|"calls"| node_org_api
node_auth_api -->|"manages"| node_sessions
node_projects_api -->|"delegates"| node_workspace_service
node_projects_api -->|"reads and writes"| node_database
node_tasks_api -->|"reads and writes"| node_database
node_crm_api -->|"reads and writes"| node_database
node_org_api -->|"reads and writes"| node_database
node_pages_api -->|"reads and writes"| node_database
node_attachments_api -->|"stores files"| node_object_store
node_attachments_api -->|"queues ingestion"| node_queue
node_kb_api -->|"reads and writes"| node_database
node_ai_threads -->|"retrieves context"| node_chunk_repo
node_ai_threads -->|"requests chat"| node_ai_provider
node_ingest -->|"consumes jobs"| node_queue
node_ingest -->|"reads files"| node_object_store
node_ingest -->|"creates embeddings"| node_ai_provider
node_ingest -->|"writes chunks"| node_chunk_repo
node_chunk_repo -->|"queries vectors"| node_database
node_ingest -->|"reads page content"| node_pages_api
node_ingest -->|"reads articles"| node_kb_api
node_ingest -->|"reads metadata"| node_attachments_api
node_queue -.->|"dispatches email jobs"| node_mail

click node_routes "https://github.com/akhmadov-360/helix/blob/main/apps/web/src/routes/_authenticated/index.tsx"
click node_board "https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/board/board-view.tsx"
click node_project_ui "https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/project-detail/project-detail-shell.tsx"
click node_content_ui "https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/pages/page-detail-view.tsx"
click node_chat_ui "https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/ai-chat/chat-drawer.tsx"
click node_transport "https://github.com/akhmadov-360/helix/blob/main/apps/web/src/shared/api/client.ts"
click node_auth_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/auth/auth.controller.ts"
click node_sessions "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/auth/sessions/refresh-session.service.ts"
click node_org_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/organizations/organizations.controller.ts"
click node_projects_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/workspaces/projects.controller.ts"
click node_tasks_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/tasks/tasks.controller.ts"
click node_crm_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/crm/contacts.controller.ts"
click node_workspace_service "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/workspaces/workspaces.service.ts"
click node_pages_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/pages/pages.controller.ts"
click node_attachments_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/attachments/attachments.controller.ts"
click node_kb_api "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/kb/kb.controller.ts"
click node_ai_threads "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/ai/ai-threads.service.ts"
click node_ingest "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/ai/ingest-embeddings.worker.ts"
click node_chunk_repo "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/ai/embedding-chunk.repository.ts"
click node_database "https://github.com/akhmadov-360/helix/blob/main/packages/db/src/index.ts"
click node_queue "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/core/queue/queue.module.ts"
click node_object_store "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/core/storage/s3.service.ts"
click node_ai_provider "https://github.com/akhmadov-360/helix/blob/main/packages/ai/src/provider-registry.ts"
click node_mail "https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/notifications/mailer/mailer.interface.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_routes,node_board,node_project_ui,node_content_ui,node_chat_ui,node_transport,node_user toneBlue
class node_auth_api,node_sessions,node_org_api toneAmber
class node_projects_api,node_tasks_api,node_crm_api,node_workspace_service toneMint
class node_pages_api,node_attachments_api,node_kb_api,node_ai_threads,node_ingest,node_chunk_repo toneRose
class node_database,node_queue,node_object_store,node_ai_provider,node_mail toneIndigo
```

## Components

### Web application

- [Routes and shell](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/routes/_authenticated/index.tsx): `apps/web/src/routes/_authenticated/index.tsx`
- [Pipeline board](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/board/board-view.tsx): `apps/web/src/features/board/board-view.tsx`
- [Project workspace UI](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/project-detail/project-detail-shell.tsx): `apps/web/src/features/project-detail/project-detail-shell.tsx`
- [Pages and files UI](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/pages/page-detail-view.tsx): `apps/web/src/features/pages/page-detail-view.tsx`
- [AI chat UI](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/features/ai-chat/chat-drawer.tsx): `apps/web/src/features/ai-chat/chat-drawer.tsx`
- [API transport](https://github.com/akhmadov-360/helix/blob/main/apps/web/src/shared/api/client.ts): `apps/web/src/shared/api/client.ts`

### Identity and access

- [Authentication API](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/auth/auth.controller.ts): `apps/api/src/modules/auth/auth.controller.ts`
- [Refresh sessions](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/auth/sessions/refresh-session.service.ts): `apps/api/src/modules/auth/sessions/refresh-session.service.ts`
- [Organization management](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/organizations/organizations.controller.ts): `apps/api/src/modules/organizations/organizations.controller.ts`

### CRM workflow

- [Projects and board](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/workspaces/projects.controller.ts): `apps/api/src/modules/workspaces/projects.controller.ts`
- [Tasks](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/tasks/tasks.controller.ts): `apps/api/src/modules/tasks/tasks.controller.ts`
- [Companies and contacts](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/crm/contacts.controller.ts): `apps/api/src/modules/crm/contacts.controller.ts`
- [Workspace services](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/workspaces/workspaces.service.ts): `apps/api/src/modules/workspaces/workspaces.service.ts`

### Workspace content and AI

- [Pages and history](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/pages/pages.controller.ts): `apps/api/src/modules/pages/pages.controller.ts`
- [Project attachments](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/attachments/attachments.controller.ts): `apps/api/src/modules/attachments/attachments.controller.ts`
- [Knowledge base](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/kb/kb.controller.ts): `apps/api/src/modules/kb/kb.controller.ts`
- [RAG chat service](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/ai/ai-threads.service.ts): `apps/api/src/modules/ai/ai-threads.service.ts`
- [Embedding ingestion](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/ai/ingest-embeddings.worker.ts): `apps/api/src/modules/ai/ingest-embeddings.worker.ts`
- [Vector chunks](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/ai/embedding-chunk.repository.ts): `apps/api/src/modules/ai/embedding-chunk.repository.ts`

### Runtime infrastructure

- [PostgreSQL and pgvector](https://github.com/akhmadov-360/helix/blob/main/packages/db/src/index.ts): `packages/db/src/index.ts`
- [Redis job queues](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/core/queue/queue.module.ts): `apps/api/src/core/queue/queue.module.ts`
- [S3-compatible storage](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/core/storage/s3.service.ts): `apps/api/src/core/storage/s3.service.ts`
- [AI provider adapters](https://github.com/akhmadov-360/helix/blob/main/packages/ai/src/provider-registry.ts): `packages/ai/src/provider-registry.ts`
- [Email delivery](https://github.com/akhmadov-360/helix/blob/main/apps/api/src/modules/notifications/mailer/mailer.interface.ts): `apps/api/src/modules/notifications/mailer/mailer.interface.ts`

### Other components

- **CRM user**

## Connections

- CRM user → Routes and shell: uses
- Routes and shell → Pipeline board: opens
- Routes and shell → Project workspace UI: opens
- Project workspace UI → Pages and files UI: opens
- Project workspace UI → AI chat UI: opens
- Pipeline board → API transport: requests
- Project workspace UI → API transport: requests
- Pages and files UI → API transport: requests
- AI chat UI → API transport: streams
- API transport → Authentication API: calls
- API transport → Projects and board: calls
- API transport → Tasks: calls
- API transport → Companies and contacts: calls
- API transport → Pages and history: calls
- API transport → Project attachments: calls
- API transport → Knowledge base: calls
- API transport → RAG chat service: calls
- API transport → Organization management: calls
- Authentication API → Refresh sessions: manages
- Projects and board → Workspace services: delegates
- Projects and board → PostgreSQL and pgvector: reads and writes
- Tasks → PostgreSQL and pgvector: reads and writes
- Companies and contacts → PostgreSQL and pgvector: reads and writes
- Organization management → PostgreSQL and pgvector: reads and writes
- Pages and history → PostgreSQL and pgvector: reads and writes
- Project attachments → S3-compatible storage: stores files
- Project attachments → Redis job queues: queues ingestion
- Knowledge base → PostgreSQL and pgvector: reads and writes
- RAG chat service → Vector chunks: retrieves context
- RAG chat service → AI provider adapters: requests chat
- Embedding ingestion → Redis job queues: consumes jobs
- Embedding ingestion → S3-compatible storage: reads files
- Embedding ingestion → AI provider adapters: creates embeddings
- Embedding ingestion → Vector chunks: writes chunks
- Vector chunks → PostgreSQL and pgvector: queries vectors
- Embedding ingestion → Pages and history: reads page content
- Embedding ingestion → Knowledge base: reads articles
- Embedding ingestion → Project attachments: reads metadata
- Redis job queues → Email delivery: dispatches email jobs