# lakshya52/flowdesk architecture

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

- Interactive diagram: https://gitdiagram.com/lakshya52/flowdesk
- Repository: https://github.com/lakshya52/flowdesk

## Overview

#### Purpose and deployable entry points
FlowDesk is a TypeScript internal-operations platform combining project/task management, calendars, CRM/field visits, chat, files, reporting, and backups. The React client starts at `client/src/main.tsx` and composes routing/application state in `client/src/App.tsx`. The Node API starts at `server/src/index.ts`. A separate Electron desktop wrapper is rooted at `desktop/src/main.ts`, with browser-to-native exposure via `desktop/src/preload.ts`.

#### Frontend application shell
The client is a React/Vite single-page application. `client/src/components/layout/AppLayout.tsx`, `client/src/components/layout/Sidebar.tsx`, and `client/src/components/layout/Header.tsx` provide authenticated application chrome around page modules under `client/src/pages/`. HTTP access is centralized in `client/src/lib/api.ts`; persisted client concerns are separated into auth, calendar, chat, and theme stores in `client/src/store/authStore.ts`, `client/src/store/calendarStore.ts`, and `client/src/store/chatStore.ts`.

#### Core workflow domains
Task and assignment work is represented by the task/board/assignment API domain and UI pages: `server/src/controllers/taskController.ts`, `server/src/controllers/assignmentController.ts`, `server/src/controllers/boardController.ts`; corresponding major views include `client/src/pages/TasksPage.tsx`, `client/src/pages/AssignmentsPage.tsx`, and `client/src/pages/BoardsPage.tsx`. Canvas-based assignment planning is a distinct feature boundary via `client/src/components/assignments/ProjectCanvas.tsx` and `server/src/controllers/canvasController.ts`.

#### Calendaring and scheduling
Calendars are a first-class subsystem with separate calendar ownership and event APIs in `server/src/routes/calendars.ts`, `server/src/routes/calendarEvents.ts`, and `server/src/controllers/calendarEventController.ts`. The client supports multiple calendar renderers and event workflows through `client/src/pages/CalendarPage.tsx`, `client/src/components/calendar/CalendarModal.tsx`, and `client/src/components/calendar/EventModal.tsx`. Google Calendar import is exposed as a dedicated backend integration route: `server/src/routes/googleCalendarImport.ts`.

#### CRM, field operations, and reporting
CRM covers leads, campaigns, summaries, and field visits, bounded by controllers such as `server/src/controllers/leadController.ts`, `server/src/controllers/campaignController.ts`, and `server/src/controllers/fieldVisitController.ts`. Field activity includes map, routing, check-in/out, expense, and location-tracking interfaces under `client/src/components/crm/`. Operational reporting is delivered through `server/src/controllers/reportController.ts` and views including `client/src/components/reports/ActivityReport.tsx` and `client/src/components/reports/EmployeeTrackingReport.tsx`.

#### Backend boundary, persistence, and real time
The API follows routes → controllers → models, with authorization and failure boundaries in `server/src/middlewares/auth.ts` and `server/src/middlewares/errorHandler.ts`. Domain persistence is model-based, including tenant/user/task/calendar/CRM entities in `server/src/models/Tenant.ts`, `server/src/models/User.ts`, and `server/src/models/Task.ts`. File handling is mediated by `server/src/middlewares/upload.ts` and GridFS utility `server/src/utils/gridfs.ts`. Real-time task, CRM, and field-visit updates are served by `server/src/services/taskSocketService.ts`, `server/src/services/crmSocketService.ts`, and `server/src/services/fieldVisitSocketService.ts`, consumed by matching client socket hooks.

#### Operations and infrastructure
Node.js is the primary server runtime; the frontend is built with Vite and can be served through Nginx (`client/Dockerfile`, `client/nginx.conf`). Dockerized deployment is defined by `docker-compose.yml`, `server/Dockerfile`, and `client/Dockerfile`. Backup scheduling and backup APIs are explicit operational services in `server/src/services/backupScheduleService.ts` and `server/src/controllers/backupController.ts`; a Windows backup task/script exists at `scripts/flowdesk-backup.ps1`. Deployment automation is present in `.github/workflows/deployOnWS.yml`.

Main entry points: [`server/src/middlewares/auth.ts`](https://github.com/lakshya52/flowdesk/blob/main/server/src/middlewares/auth.ts) (Routes and middleware), [`client/src/components/layout/AppLayout.tsx`](https://github.com/lakshya52/flowdesk/blob/main/client/src/components/layout/AppLayout.tsx) (Authenticated layout), [`client/src/App.tsx`](https://github.com/lakshya52/flowdesk/blob/main/client/src/App.tsx) (App routing and state), [`client/src/lib/api.ts`](https://github.com/lakshya52/flowdesk/blob/main/client/src/lib/api.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["React client"]
  node_client_entry["Vite entry<br/>React bootstrap<br/>[main.tsx]"]
  node_client_app["App routing and state<br/>application shell<br/>[App.tsx]"]
  node_client_layout["Authenticated layout<br/>application chrome<br/>[AppLayout.tsx]"]
  node_client_api["HTTP client<br/>API access<br/>[api.ts]"]
  node_client_stores["Client stores<br/>persisted state<br/>[authStore.ts]"]
  node_work_ui["Work management UI<br/>task and board views<br/>[TasksPage.tsx]"]
  node_calendar_ui["Calendar UI<br/>calendar workflows<br/>[CalendarPage.tsx]"]
  node_crm_reports_ui["CRM and reports UI<br/>field operations views"]
end

subgraph group_api["Node API"]
  node_api_entry["API server<br/>Node entry point<br/>[index.ts]"]
  node_api_boundary["Routes and middleware<br/>HTTP boundary<br/>[auth.ts]"]
  node_work_api["Work and canvas domain<br/>controllers<br/>[taskController.ts]"]
  node_calendar_api["Calendar domain<br/>routes and controllers<br/>[calendars.ts]"]
  node_crm_reports_api["CRM and reporting domain<br/>controllers<br/>[leadController.ts]"]
  node_models[("Domain models<br/>persistence layer<br/>[Tenant.ts]")]
  node_realtime["Realtime services<br/>socket services"]
  node_files[("File storage<br/>upload and GridFS<br/>[upload.ts]")]
end

subgraph group_desktop["Desktop"]
  node_desktop_main["Electron wrapper<br/>desktop runtime<br/>[main.ts]"]
end

subgraph group_ops["Operations"]
  node_backups["Backup services<br/>scheduled operations"]
  node_deployment{{"Container deployment<br/>Docker and CI<br/>[docker-compose.yml]"}}
end

node_client_entry -->|"boots"| node_client_app
node_client_app -->|"renders"| node_client_layout
node_client_app -->|"uses"| node_client_stores
node_client_layout -->|"hosts"| node_work_ui
node_client_layout -->|"hosts"| node_calendar_ui
node_client_layout -->|"hosts"| node_crm_reports_ui
node_work_ui -->|"requests"| node_client_api
node_calendar_ui -->|"requests"| node_client_api
node_crm_reports_ui -->|"requests"| node_client_api
node_client_api -->|"HTTP"| node_api_entry
node_api_entry -->|"dispatches"| node_api_boundary
node_api_boundary -->|"authorizes"| node_work_api
node_api_boundary -->|"authorizes"| node_calendar_api
node_api_boundary -->|"authorizes"| node_crm_reports_api
node_work_api -->|"persists"| node_models
node_calendar_api -->|"persists"| node_models
node_crm_reports_api -->|"persists"| node_models
node_api_boundary -->|"uploads"| node_files
node_work_api -->|"publishes updates"| node_realtime
node_crm_reports_api -->|"publishes updates"| node_realtime
node_backups -.->|"backs up"| node_models
node_desktop_main -->|"hosts"| node_client_app
node_deployment -.->|"deploys"| node_api_entry
node_deployment -.->|"builds and serves"| node_client_entry

click node_client_entry "https://github.com/lakshya52/flowdesk/blob/main/client/src/main.tsx"
click node_client_app "https://github.com/lakshya52/flowdesk/blob/main/client/src/App.tsx"
click node_client_layout "https://github.com/lakshya52/flowdesk/blob/main/client/src/components/layout/AppLayout.tsx"
click node_client_api "https://github.com/lakshya52/flowdesk/blob/main/client/src/lib/api.ts"
click node_client_stores "https://github.com/lakshya52/flowdesk/blob/main/client/src/store/authStore.ts"
click node_work_ui "https://github.com/lakshya52/flowdesk/blob/main/client/src/pages/TasksPage.tsx"
click node_calendar_ui "https://github.com/lakshya52/flowdesk/blob/main/client/src/pages/CalendarPage.tsx"
click node_api_entry "https://github.com/lakshya52/flowdesk/blob/main/server/src/index.ts"
click node_api_boundary "https://github.com/lakshya52/flowdesk/blob/main/server/src/middlewares/auth.ts"
click node_work_api "https://github.com/lakshya52/flowdesk/blob/main/server/src/controllers/taskController.ts"
click node_calendar_api "https://github.com/lakshya52/flowdesk/blob/main/server/src/routes/calendars.ts"
click node_crm_reports_api "https://github.com/lakshya52/flowdesk/blob/main/server/src/controllers/leadController.ts"
click node_models "https://github.com/lakshya52/flowdesk/blob/main/server/src/models/Tenant.ts"
click node_realtime "https://github.com/lakshya52/flowdesk/blob/main/server/src/services/taskSocketService.ts"
click node_files "https://github.com/lakshya52/flowdesk/blob/main/server/src/middlewares/upload.ts"
click node_backups "https://github.com/lakshya52/flowdesk/blob/main/server/src/services/backupScheduleService.ts"
click node_desktop_main "https://github.com/lakshya52/flowdesk/blob/main/desktop/src/main.ts"
click node_deployment "https://github.com/lakshya52/flowdesk/blob/main/docker-compose.yml"

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_client_entry,node_client_app,node_client_layout,node_client_api,node_client_stores,node_work_ui,node_calendar_ui,node_crm_reports_ui toneBlue
class node_api_entry,node_api_boundary,node_work_api,node_calendar_api,node_crm_reports_api,node_models,node_realtime,node_files toneAmber
class node_desktop_main toneMint
class node_backups,node_deployment toneRose
```

## Components

### React client

- [Vite entry](https://github.com/lakshya52/flowdesk/blob/main/client/src/main.tsx): React bootstrap · `client/src/main.tsx`
- [App routing and state](https://github.com/lakshya52/flowdesk/blob/main/client/src/App.tsx): application shell · `client/src/App.tsx`
- [Authenticated layout](https://github.com/lakshya52/flowdesk/blob/main/client/src/components/layout/AppLayout.tsx): application chrome · Layout, sidebar, and header wrap page modules. · `client/src/components/layout/AppLayout.tsx`
- [HTTP client](https://github.com/lakshya52/flowdesk/blob/main/client/src/lib/api.ts): API access · `client/src/lib/api.ts`
- [Client stores](https://github.com/lakshya52/flowdesk/blob/main/client/src/store/authStore.ts): persisted state · Auth, calendar, chat, and theme state. · `client/src/store/authStore.ts`
- [Work management UI](https://github.com/lakshya52/flowdesk/blob/main/client/src/pages/TasksPage.tsx): task and board views · Tasks, assignments, boards, and canvas planning. · `client/src/pages/TasksPage.tsx`
- [Calendar UI](https://github.com/lakshya52/flowdesk/blob/main/client/src/pages/CalendarPage.tsx): calendar workflows · Calendar views plus calendar and event modals. · `client/src/pages/CalendarPage.tsx`
- **CRM and reports UI**: field operations views · CRM field activity and operational reports.

### Node API

- [API server](https://github.com/lakshya52/flowdesk/blob/main/server/src/index.ts): Node entry point · `server/src/index.ts`
- [Routes and middleware](https://github.com/lakshya52/flowdesk/blob/main/server/src/middlewares/auth.ts): HTTP boundary · Authentication, errors, uploads, and route dispatch. · `server/src/middlewares/auth.ts`
- [Work and canvas domain](https://github.com/lakshya52/flowdesk/blob/main/server/src/controllers/taskController.ts): controllers · Task, assignment, board, and canvas operations. · `server/src/controllers/taskController.ts`
- [Calendar domain](https://github.com/lakshya52/flowdesk/blob/main/server/src/routes/calendars.ts): routes and controllers · Calendar ownership, events, and Google import. · `server/src/routes/calendars.ts`
- [CRM and reporting domain](https://github.com/lakshya52/flowdesk/blob/main/server/src/controllers/leadController.ts): controllers · Leads, campaigns, field visits, and reports. · `server/src/controllers/leadController.ts`
- [Domain models](https://github.com/lakshya52/flowdesk/blob/main/server/src/models/Tenant.ts): persistence layer · Tenant, user, task, calendar, and CRM entities. · `server/src/models/Tenant.ts`
- [Realtime services](https://github.com/lakshya52/flowdesk/blob/main/server/src/services/taskSocketService.ts): socket services · Task, CRM, and field-visit updates. · `server/src/services/taskSocketService.ts`
- [File storage](https://github.com/lakshya52/flowdesk/blob/main/server/src/middlewares/upload.ts): upload and GridFS · `server/src/middlewares/upload.ts`

### Desktop

- [Electron wrapper](https://github.com/lakshya52/flowdesk/blob/main/desktop/src/main.ts): desktop runtime · Native main process and browser bridge. · `desktop/src/main.ts`

### Operations

- [Backup services](https://github.com/lakshya52/flowdesk/blob/main/server/src/services/backupScheduleService.ts): scheduled operations · `server/src/services/backupScheduleService.ts`
- [Container deployment](https://github.com/lakshya52/flowdesk/blob/main/docker-compose.yml): Docker and CI · Compose deployment with frontend Nginx and workflow automation. · `docker-compose.yml`

## Connections

- Vite entry → App routing and state: boots
- App routing and state → Authenticated layout: renders
- App routing and state → Client stores: uses
- Authenticated layout → Work management UI: hosts
- Authenticated layout → Calendar UI: hosts
- Authenticated layout → CRM and reports UI: hosts
- Work management UI → HTTP client: requests
- Calendar UI → HTTP client: requests
- CRM and reports UI → HTTP client: requests
- HTTP client → API server: HTTP
- API server → Routes and middleware: dispatches
- Routes and middleware → Work and canvas domain: authorizes
- Routes and middleware → Calendar domain: authorizes
- Routes and middleware → CRM and reporting domain: authorizes
- Work and canvas domain → Domain models: persists
- Calendar domain → Domain models: persists
- CRM and reporting domain → Domain models: persists
- Routes and middleware → File storage: uploads
- Work and canvas domain → Realtime services: publishes updates
- CRM and reporting domain → Realtime services: publishes updates
- Backup services → Domain models: backs up
- Electron wrapper → App routing and state: hosts
- Container deployment → API server: deploys
- Container deployment → Vite entry: builds and serves