How elonerajeev/flowsyc works
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: leads.service.ts Domain Services · app.ts API Layer · docker-compose.yml Compose · prometheus.yml Prometheus
Components 21
Ops
Root deployment, CI/CD, and local orchestration
Frontend
React SPA and public site
- UI Shell · App entry, routing, and layouts
frontend/src/App.tsx - App State · Auth, workspace, theme, notifications, realtime
frontend/src/contexts/AuthContext.tsx - Pages · Landing, auth, and business screens
frontend/src/pages/Dashboard.tsx - Widgets · CRM, dashboard, landing, and automation components
frontend/src/components/crm/ClientCard.tsx - Client API · HTTP-facing service abstractions
frontend/src/services/crm.ts - Shared UI · Layouts, guards, error boundaries, and primitives
frontend/src/components/layout/AppLayout.tsx
Backend
Express API and domain services
- API Layer · App bootstrap, routes, controllers, and middleware
backend/src/app.ts - Routes · HTTP endpoints grouped by domain
backend/src/routes/leads.routes.ts - Domain Services · CRM, projects, finance, HR, inbox, automation, and reports
backend/src/services/leads.service.ts - Middleware · Auth, rate limit, validation, metrics, and errors
backend/src/middleware/auth.middleware.ts - Realtime · Live notifications and updates
backend/src/socket.ts - Prisma DB · Schema and migrations for PostgreSQL-backed storage
backend/prisma/schema.prisma - Inbox · Email sync, templates, and communication workflows
backend/src/services/inbox.service.ts - Automation · Rules, GTM lifecycle, and automation triggers
backend/src/services/automation-engine.ts
Monitoring
Metrics, logs, dashboards, and alerts
- Prometheus · Metrics collection and alert evaluation
monitoring/prometheus.yml - Grafana · Operational dashboards and visualization
monitoring/grafana/dashboards/crm-monitoring.json - Loki · Centralized log aggregation
monitoring/loki-config.yml - Alerting · Alertmanager and alert rules
monitoring/alertmanager.yml
Connections 24
- 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