# elonerajeev/flowsyc architecture

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

- Interactive diagram: https://gitdiagram.com/elonerajeev/flowsyc
- Repository: https://github.com/elonerajeev/flowsyc

## Overview

1. **Repository shape**
   - This is a full-stack monorepo with three operational parts: `frontend/` (React SPA), `backend/` (Express API), and `monitoring/` (Prometheus/Grafana/Loki/Alertmanager).
   - Root-level Docker, CI/CD, and deployment scripts support local compose runs and production-style deployments.

2. **Primary runtime boundary**
   - The frontend is the user-facing application and serves pages for CRM, projects, HR, finance, automation, inbox, and analytics.
   - The backend is the system of record: it owns authentication, authorization, business rules, data validation, persistence, and real-time events.
   - The frontend communicates with the backend over HTTP for CRUD and over Socket.IO for live updates/notifications.

3. **Frontend architecture**
   - Built with React 18, TypeScript, Vite, Tailwind, and shadcn/ui.
   - It is organized around route-level pages in `src/pages/`, shared layout shells in `src/components/layout/`, reusable UI primitives in `src/components/ui/`, and feature widgets in `src/components/crm/`, `dashboard/`, `automation/`, etc.
   - Data access is abstracted through `src/services/`, custom hooks, and context providers, not directly embedded in page components.

4. **Frontend state and cross-cutting concerns**
   - `AuthContext`, `WorkspaceContext`, `ThemeContext`, `NotificationContext`, and `RealtimeContext` define app-wide state boundaries.
   - Route guards and admin-only wrappers enforce UI-level access control, while error boundaries and monitoring hooks handle resilience and observability.
   - The frontend includes both business pages and a marketing/landing experience, indicating the same repo serves public site plus authenticated app.

5. **Backend architecture**
   - Built with Express.js and TypeScript, structured into controllers, routes, services, middleware, validators, and utilities.
   - `routes/` defines API surface area, `controllers/` translate HTTP into application calls, `services/` contain business logic, and `validators/` enforce Zod-based request contracts.
   - `middleware/` handles auth, rate limiting, validation, metrics, and error handling, making these the main API boundary controls.

6. **Domain modules on the backend**
   - The backend is modular by business area: clients, leads, deals, projects, tasks, notes, invoices, payroll, attendance, hiring/candidates, inbox, teams/team-members, reports, dashboard, automation, and preferences.
   - Supporting modules such as attachments, comments, activities, search, notifications, calendar, and meetings connect the core business entities.
   - There is also a `static-crm` path backed by `src/data/crm-static.ts` and a dedicated service, suggesting some seeded or read-only CRM content alongside dynamic records.

7. **Persistence and schema**
   - Prisma is the persistence layer, with `backend/prisma/schema.prisma` and a long migration history that shows the schema evolved into a multi-module business platform.
   - PostgreSQL is the intended database, and the migrations cover audit logs, teams, calendar/payroll, inbox IMAP models, team-member linking, and unique constraints for org-scoped data.
   - The repo includes a checked-in `dev.db`, indicating local development support, but the architectural source of truth is the Prisma/PostgreSQL model.

8. **Real-time and integration flows**
   - Socket.IO is part of the backend architecture and is surfaced to the frontend through a realtime context, mainly for notifications and live dashboard-style updates.
   - Email and inbox functionality are first-class: SMTP mail via Nodemailer, Google OAuth, IMAP-based inbox syncing, and email templates support communication workflows.
   - File upload/storage is also a subsystem, with attachment routes/services and storage/image-optimization helpers indicating local or cloud-backed file handling.

9. **Automation and orchestration**
   - Automation is not an add-on; it has dedicated routes, service logic, schema validation, and engine-like components.
   - The backend includes GTM-related automation/lifecycle services, suggesting workflow triggers based on lead or lifecycle changes.
   - These flows likely emit notifications, update audit/activity logs, and interact with CRM entities rather than living as a separate service.

10. **Security and access boundaries**
   - Authentication is JWT-based with access/refresh tokens, plus optional Google sign-in.
   - Authorization is enforced in backend utilities and middleware, with tests specifically covering access control and auth APIs.
   - Audit logging is a separate concern with dedicated database migrations and helper utilities, so critical actions are traceable across modules.

11. **Observability and operational tooling**
   - The repo includes backend metrics middleware plus a full monitoring stack under `monitoring/` with Prometheus, Grafana dashboards, Loki, and alert rules.
   - Logging, metrics, and error tracking are treated as architecture-level concerns rather than ad hoc utilities.
   - This makes the system diagram broader than just app/database: it also has a runtime observability plane.

12. **Deployment and environment model**
   - Dockerfiles exist for both frontend and backend, and `docker-compose.yml` supports local orchestration.
   - The README and scripts imply a common deployment split: frontend deployed separately from the backend, with the frontend pointed at API and WebSocket endpoints.
   - GitHub Actions workflows plus helper scripts for setup, deployment, and smoke tests show the repo is designed for repeatable CI/CD and environment bootstrapping.

13. **Testing and developer workflow**
   - Backend tests cover services, controllers, validation, and auth; frontend tests cover pages, services, and shared UI.
   - There are many seed/bootstrap scripts for realistic data, smoke testing, and operational checks, which suggests architecture that relies on seeded workflows and end-to-end verification.
   - For a diagram, this means there is a strong dev/test path alongside the production path: seed scripts -> database -> API -> UI.

14. **How the main data flows connect**
   - User actions start in the frontend page/component layer, pass through service hooks, then hit REST routes on the backend.
   - Backend controllers validate and authorize the request, services apply business logic, Prisma writes to PostgreSQL, and side effects may emit audit events, notifications, emails, or realtime messages.
   - The frontend then refreshes query state or receives live updates through Socket.IO, closing the loop for dashboards, inbox, task boards, and activity feeds.

Main entry points: [`backend/src/services/leads.service.ts`](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/services/leads.service.ts) (Domain Services), [`backend/src/app.ts`](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/app.ts) (API Layer), [`docker-compose.yml`](https://github.com/elonerajeev/flowsyc/blob/main/docker-compose.yml) (Compose), [`monitoring/prometheus.yml`](https://github.com/elonerajeev/flowsyc/blob/main/monitoring/prometheus.yml) (Prometheus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ops["Ops"]
  node_compose["Compose<br/>orchestration<br/>[docker-compose.yml]"]
  node_ci["CI/CD<br/>automation<br/>[ci.yml]"]
  node_deploy["Deploy<br/>release script<br/>[deploy.sh]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["UI Shell<br/>React app<br/>[App.tsx]"]
  node_frontend_contexts["App State<br/>contexts<br/>[AuthContext.tsx]"]
  node_frontend_pages["Pages<br/>[Dashboard.tsx]"]
  node_frontend_widgets["Widgets<br/>feature UI<br/>[ClientCard.tsx]"]
  node_frontend_services["Client API<br/>service layer<br/>[crm.ts]"]
  node_frontend_shared["Shared UI<br/>design system<br/>[AppLayout.tsx]"]
end

subgraph group_backend["Backend"]
  node_backend_api["API Layer<br/>express entry<br/>[app.ts]"]
  node_backend_routes["Routes<br/>api surface<br/>[leads.routes.ts]"]
  node_backend_services["Domain Services<br/>business logic<br/>[leads.service.ts]"]
  node_backend_middleware["Middleware<br/>boundary controls<br/>[auth.middleware.ts]"]
  node_backend_socket(("Realtime<br/>socket.io<br/>[socket.ts]"))
  node_backend_prisma[("Prisma DB<br/>persistence<br/>[schema.prisma]")]
  node_backend_inbox["Inbox<br/>integration module<br/>[inbox.service.ts]"]
  node_backend_automation{{"Automation<br/>workflow engine"}}
end

subgraph group_monitoring["Monitoring"]
  node_monitor_prom["Prometheus<br/>metrics<br/>[prometheus.yml]"]
  node_monitor_grafana["Grafana<br/>dashboards"]
  node_monitor_loki["Loki<br/>logs<br/>[loki-config.yml]"]
  node_monitor_alerts["Alerting<br/>alerts<br/>[alertmanager.yml]"]
end

node_compose -->|"runs"| node_frontend_app
node_compose -->|"runs"| node_backend_api
node_compose -->|"includes"| node_monitor_prom
node_ci -->|"publishes"| node_deploy
node_deploy -->|"orchestrates"| node_compose
node_frontend_app -->|"uses"| node_frontend_contexts
node_frontend_app -->|"renders"| node_frontend_shared
node_frontend_pages -->|"loads data"| node_frontend_services
node_frontend_pages -->|"composes"| node_frontend_widgets
node_frontend_services -->|"HTTP"| node_backend_routes
node_frontend_contexts -->|"subscribes"| node_backend_socket
node_backend_api -->|"mounts"| node_backend_routes
node_backend_api -->|"protects"| node_backend_middleware
node_backend_routes -->|"delegates"| node_backend_services
node_backend_services -->|"persists"| node_backend_prisma
node_backend_services -->|"emits"| node_backend_socket
node_backend_services -->|"integrates"| node_backend_inbox
node_backend_services -->|"triggers"| node_backend_automation
node_backend_middleware -->|"validates"| node_backend_prisma
node_backend_middleware -->|"measures"| node_monitor_prom
node_monitor_prom -->|"visualized by"| node_monitor_grafana
node_monitor_prom -->|"alerts"| node_monitor_alerts
node_backend_api -->|"logs to"| node_monitor_loki
node_backend_socket -->|"updates"| node_frontend_contexts

click node_compose "https://github.com/elonerajeev/flowsyc/blob/main/docker-compose.yml"
click node_ci "https://github.com/elonerajeev/flowsyc/blob/main/.github/workflows/ci.yml"
click node_deploy "https://github.com/elonerajeev/flowsyc/blob/main/scripts/deploy.sh"
click node_frontend_app "https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/App.tsx"
click node_frontend_contexts "https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_frontend_pages "https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/pages/Dashboard.tsx"
click node_frontend_widgets "https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/components/crm/ClientCard.tsx"
click node_frontend_services "https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/services/crm.ts"
click node_frontend_shared "https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/components/layout/AppLayout.tsx"
click node_backend_api "https://github.com/elonerajeev/flowsyc/blob/main/backend/src/app.ts"
click node_backend_routes "https://github.com/elonerajeev/flowsyc/blob/main/backend/src/routes/leads.routes.ts"
click node_backend_services "https://github.com/elonerajeev/flowsyc/blob/main/backend/src/services/leads.service.ts"
click node_backend_middleware "https://github.com/elonerajeev/flowsyc/blob/main/backend/src/middleware/auth.middleware.ts"
click node_backend_socket "https://github.com/elonerajeev/flowsyc/blob/main/backend/src/socket.ts"
click node_backend_prisma "https://github.com/elonerajeev/flowsyc/blob/main/backend/prisma/schema.prisma"
click node_backend_inbox "https://github.com/elonerajeev/flowsyc/blob/main/backend/src/services/inbox.service.ts"
click node_backend_automation "https://github.com/elonerajeev/flowsyc/blob/main/backend/src/services/automation-engine.ts"
click node_monitor_prom "https://github.com/elonerajeev/flowsyc/blob/main/monitoring/prometheus.yml"
click node_monitor_grafana "https://github.com/elonerajeev/flowsyc/blob/main/monitoring/grafana/dashboards/crm-monitoring.json"
click node_monitor_loki "https://github.com/elonerajeev/flowsyc/blob/main/monitoring/loki-config.yml"
click node_monitor_alerts "https://github.com/elonerajeev/flowsyc/blob/main/monitoring/alertmanager.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_compose,node_ci,node_deploy toneBlue
class node_frontend_app,node_frontend_contexts,node_frontend_pages,node_frontend_widgets,node_frontend_services,node_frontend_shared toneAmber
class node_backend_api,node_backend_routes,node_backend_services,node_backend_middleware,node_backend_socket,node_backend_prisma,node_backend_inbox,node_backend_automation toneMint
class node_monitor_prom,node_monitor_grafana,node_monitor_loki,node_monitor_alerts toneRose
```

## Components

### Ops

Root deployment, CI/CD, and local orchestration

- [Compose](https://github.com/elonerajeev/flowsyc/blob/main/docker-compose.yml): orchestration · Local multi-service runtime · `docker-compose.yml`
- [CI/CD](https://github.com/elonerajeev/flowsyc/blob/main/.github/workflows/ci.yml): automation · Build and deployment workflows · `.github/workflows/ci.yml`
- [Deploy](https://github.com/elonerajeev/flowsyc/blob/main/scripts/deploy.sh): release script · Production deployment helper · `scripts/deploy.sh`

### Frontend

React SPA and public site

- [UI Shell](https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/App.tsx): React app · App entry, routing, and layouts · `frontend/src/App.tsx`
- [App State](https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/contexts/AuthContext.tsx): contexts · Auth, workspace, theme, notifications, realtime · `frontend/src/contexts/AuthContext.tsx`
- [Pages](https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/pages/Dashboard.tsx): route pages · Landing, auth, and business screens · `frontend/src/pages/Dashboard.tsx`
- [Widgets](https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/components/crm/ClientCard.tsx): feature UI · CRM, dashboard, landing, and automation components · `frontend/src/components/crm/ClientCard.tsx`
- [Client API](https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/services/crm.ts): service layer · HTTP-facing service abstractions · `frontend/src/services/crm.ts`
- [Shared UI](https://github.com/elonerajeev/flowsyc/blob/main/frontend/src/components/layout/AppLayout.tsx): design system · Layouts, guards, error boundaries, and primitives · `frontend/src/components/layout/AppLayout.tsx`

### Backend

Express API and domain services

- [API Layer](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/app.ts): express entry · App bootstrap, routes, controllers, and middleware · `backend/src/app.ts`
- [Routes](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/routes/leads.routes.ts): api surface · HTTP endpoints grouped by domain · `backend/src/routes/leads.routes.ts`
- [Domain Services](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/services/leads.service.ts): business logic · CRM, projects, finance, HR, inbox, automation, and reports · `backend/src/services/leads.service.ts`
- [Middleware](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/middleware/auth.middleware.ts): boundary controls · Auth, rate limit, validation, metrics, and errors · `backend/src/middleware/auth.middleware.ts`
- [Realtime](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/socket.ts): socket.io · Live notifications and updates · `backend/src/socket.ts`
- [Prisma DB](https://github.com/elonerajeev/flowsyc/blob/main/backend/prisma/schema.prisma): persistence · Schema and migrations for PostgreSQL-backed storage · `backend/prisma/schema.prisma`
- [Inbox](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/services/inbox.service.ts): integration module · Email sync, templates, and communication workflows · `backend/src/services/inbox.service.ts`
- [Automation](https://github.com/elonerajeev/flowsyc/blob/main/backend/src/services/automation-engine.ts): workflow engine · Rules, GTM lifecycle, and automation triggers · `backend/src/services/automation-engine.ts`

### Monitoring

Metrics, logs, dashboards, and alerts

- [Prometheus](https://github.com/elonerajeev/flowsyc/blob/main/monitoring/prometheus.yml): metrics · Metrics collection and alert evaluation · `monitoring/prometheus.yml`
- [Grafana](https://github.com/elonerajeev/flowsyc/blob/main/monitoring/grafana/dashboards/crm-monitoring.json): dashboards · Operational dashboards and visualization · `monitoring/grafana/dashboards/crm-monitoring.json`
- [Loki](https://github.com/elonerajeev/flowsyc/blob/main/monitoring/loki-config.yml): logs · Centralized log aggregation · `monitoring/loki-config.yml`
- [Alerting](https://github.com/elonerajeev/flowsyc/blob/main/monitoring/alertmanager.yml): alerts · Alertmanager and alert rules · `monitoring/alertmanager.yml`

## Connections

- Compose → UI Shell: runs · Compose can start the frontend runtime
- Compose → API Layer: runs · Compose can start the backend runtime
- Compose → Prometheus: includes · Local stack includes monitoring services
- CI/CD → Deploy: publishes · CI/CD feeds deployment automation
- Deploy → Compose: orchestrates · Deployment helpers align local and production-style runtime
- UI Shell → App State: uses · UI shell is wrapped by app-wide state providers
- UI Shell → Shared UI: renders · Layouts and access guards structure the app
- Pages → Client API: loads data · Pages call service abstractions for server data
- Pages → Widgets: composes · Route pages assemble feature widgets
- Client API → Routes: HTTP · Client services call the API surface
- App State → Realtime: subscribes · Realtime state listens for socket events
- API Layer → Routes: mounts · App entry wires route modules
- API Layer → Middleware: protects · Middleware enforces request boundaries
- Routes → Domain Services: delegates · Routes hand off to domain services
- Domain Services → Prisma DB: persists · Business logic reads and writes the database
- Domain Services → Realtime: emits · Services can publish live events
- Domain Services → Inbox: integrates · Communication workflows are handled by inbox services
- Domain Services → Automation: triggers · Domain events feed automation flows
- Middleware → Prisma DB: validates · Validation and auth rely on persistent state and schemas
- Middleware → Prometheus: measures · Metrics middleware exports API telemetry
- Prometheus → Grafana: visualized by · Prometheus data is displayed in dashboards
- Prometheus → Alerting: alerts · Metric rules drive alerting
- API Layer → Loki: logs to · Application logs feed centralized logging
- Realtime → App State: updates · Live messages refresh client state
