# dm1tryandreev1ch/flex-n-roll-pro architecture

> Architecture diagram of the GitHub repository dm1tryandreev1ch/flex-n-roll-pro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dm1tryandreev1ch/flex-n-roll-pro
- Repository: https://github.com/dm1tryandreev1ch/flex-n-roll-pro

## Overview

1. **Repository shape**
   This is a Dockerized Node.js monorepo for a label-printing business. The central external system is **Bitrix24 CRM**; most services either consume Bitrix events, call Bitrix REST APIs, or read CRM data for reporting. The only non-CRM user-facing apps are the **calculator SPA** and the **analytics dashboard**.

2. **Core control plane: `webhook/`**
   `fnr-webhook` is the main event ingress. It receives Bitrix24 OAuth callbacks and subscribed CRM events, authenticates/rate-limits them, and then fans out work to other services. It is the orchestration layer for:
   - lead classification and manager routing,
   - event forwarding to call analysis,
   - event forwarding to marking,
   - event binding/subscription management during install.

3. **Lead routing flow**
   Incoming Bitrix lead events are classified by `webhook` using a local LLM endpoint via **LM Studio** (`host.docker.internal:1234`). Based on the classification, the service assigns leads to managers, using **Redis** for state such as round-robin counters and possibly deduplication/rate limiting. This is the main “automation brain” of the platform.

4. **Call analysis subsystem: `commanalysis/`**
   `fnr-commanalysis` handles call-related events from Bitrix. Its pipeline is:
   - receive call end events or batch jobs,
   - fetch audio / call metadata from Bitrix,
   - transcribe with **OpenAI Whisper**,
   - score or summarize with GPT-based prompts (`sentiment`, `scriptCheck`, `dataExtract`),
   - emit metrics, logs, and reports.
   A separate `scheduler/dailyBatch.js` job generates daily summaries, so this service has both request-driven and cron-driven execution paths.

5. **Marking subsystem: `marking/`**
   `fnr-marking` is the integration boundary for **Честный ЗНАК / GIS MT** workflows. It processes CRM deal updates, manages product codes, and generates **DataMatrix** codes. The repo structure suggests a split between:
   - route layer (`routes/marking.js`, `routes/webhook.js`),
   - Bitrix adapter,
   - domain services for code management and MDLP integration,
   - utility-level DataMatrix generation.
   It also persists marking-related files/state locally in its data volume.

6. **Telegram order status bot: `fnr-status-bot/`**
   This service is a long-polling Telegram bot. It provides a lightweight lookup channel for deal/order status against Bitrix24. The code is organized as:
   - bot bootstrap,
   - scene-based conversation flow (`scenes/checkOrder.js`),
   - Bitrix integration service,
   - formatting and keyboard helpers.
   It is user-facing, but it is not part of the web frontend stack.

7. **Calculator subsystem: `calculator/`**
   The calculator is a two-part service:
   - a **React + Vite SPA** served by Nginx,
   - a small **Express API** (`server.js`) used for Bitrix integration and server-side calculations.
   The frontend is organized around a multi-step calculator flow (`StepOne`, `StepTwo`, `StepThree`, `PriceResult`, `LeadForm`) with shared pricing logic in `utils/priceCalc.ts` and hooks like `useCalculator` and `useBitrix`. This is a separate compose stack from the main backend services.

8. **Analytics dashboard: `fnr-analytics/`**
   `fnr-analytics` is another React + Vite SPA, focused on reporting rather than transactions. It pulls data from Bitrix through `src/api/bitrix.ts` and renders pages for:
   - dashboard,
   - deals,
   - contacts,
   - activities,
   - managers report,
   - finance report,
   - settings/login.
   It appears to be a read-heavy front end with export support (`ExportButton`, `exportExcel.ts`) and role-based access.

9. **Shared infrastructure: Redis, Docker Compose, and networking**
   The main stack runs on a Docker bridge network (`fnr-net`). Services talk to each other by container name. **Redis** is a shared infrastructure dependency for caching, counters, and rate limiting, especially in webhook/routing logic. The repo uses multiple compose files:
   - `docker-compose.yml` for the core backend services,
   - `docker-compose.calculator.yml` for the calculator stack,
   - `docker-compose.monitoring.yml` for Prometheus/Grafana.

10. **Observability boundary**
   Several backend services expose `/metrics`, and the `monitoring/` directory provisions **Prometheus** scraping plus **Grafana** dashboards. This is a cross-cutting subsystem rather than business logic. Dashboard provisioning is committed in-repo, so monitoring is treated as part of the application architecture, not an external add-on.

11. **Integration boundaries**
   The biggest external dependencies are:
   - **Bitrix24** as CRM/system of record,
   - **LM Studio** as the local LLM endpoint used by webhook routing,
   - **OpenAI APIs** for commanalysis,
   - **Telegram Bot API** for status lookup,
   - **GIS MT / Честный ЗНАК** for marking.
   These are separated into service-specific adapters rather than being called directly from the UI.

12. **Diagramming the repo**
   If drawing the architecture, center everything around **Bitrix24 + webhook orchestration + Redis**. Then show four major consumers:
   - `commanalysis` for call intelligence,
   - `marking` for production marking,
   - `fnr-status-bot` for human status lookup,
   - `calculator` and `fnr-analytics` as browser-facing applications.
   Overlay Prometheus/Grafana as shared observability, and treat Docker Compose as the deployment boundary that glues all containers together.

Main entry points: [`commanalysis/src/server.js`](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/src/server.js) (fnr-commanalysis), [`webhook/src/server.js`](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/server.js) (fnr-webhook), [`monitoring/prometheus/prometheus.yml`](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/monitoring/prometheus/prometheus.yml) (Prometheus), [`docker-compose.yml`](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/docker-compose.yml) (Core compose)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External systems"]
  node_bitrix24[("Bitrix24<br/>crm system")]
  node_redis[("Redis<br/>state cache")]
  node_lmstudio[("LM Studio<br/>local llm")]
  node_openai[("OpenAI<br/>ai api")]
  node_telegram[("Telegram<br/>bot api")]
  node_gismt[("GIS MT<br/>marking system")]
end

subgraph group_control["Control plane"]
  node_webhook["fnr-webhook<br/>event orchestrator<br/>[server.js]"]
  node_auth["Auth/rate limit<br/>middleware<br/>[auth.js]"]
  node_routing["Routing engine<br/>[routing.js]"]
  node_eventbinder["Event binder<br/>[eventBinder.js]"]
  node_commanalysis["fnr-commanalysis<br/>call intelligence<br/>[server.js]"]
  node_whisper["Transcription<br/>[whisper.js]"]
  node_callanalyzer["Call analysis<br/>pipeline<br/>[callAnalyzer.js]"]
  node_dailybatch["Daily batch<br/>scheduler<br/>[dailyBatch.js]"]
  node_marking["fnr-marking<br/>marking integration<br/>[server.js]"]
  node_codemanager["Code manager<br/>[codeManager.js]"]
  node_mdlp["MDLP adapter<br/>integration<br/>[mdlp.js]"]
  node_datamatrix(("DataMatrix<br/>[datamatrix.js]"))
  node_bitrixapi["Bitrix API client<br/>adapter<br/>[bitrix.js]"]
end

subgraph group_apps["User apps"]
  node_statusbot["fnr-status-bot<br/>telegram bot<br/>[bot.js]"]
  node_checkorder["Order lookup<br/>scene<br/>[checkOrder.js]"]
  node_calculator["Calculator SPA<br/>react app<br/>[App.tsx]"]
  node_calcapi["Calculator API<br/>express api<br/>[server.js]"]
  node_analytics["Analytics dashboard<br/>react app<br/>[App.tsx]"]
end

subgraph group_ops["Operations"]
  node_composecore["Core compose<br/>deployment stack<br/>[docker-compose.yml]"]
  node_composecalc["Calculator compose<br/>deployment stack"]
  node_composemon["Monitoring compose<br/>deployment stack"]
  node_prometheus["Prometheus<br/>metrics scrape<br/>[prometheus.yml]"]
  node_grafana["Grafana<br/>dashboards<br/>[fnr-overview.json]"]
end

node_webhook -->|"protects"| node_auth
node_webhook -->|"classifies"| node_routing
node_webhook -->|"binds"| node_eventbinder
node_webhook -->|"calls"| node_bitrixapi
node_routing -->|"asks"| node_lmstudio
node_routing -->|"uses"| node_redis
node_routing -->|"updates"| node_bitrix24
node_webhook -->|"forwards"| node_commanalysis
node_commanalysis -->|"reads"| node_bitrix24
node_commanalysis -->|"transcribes"| node_whisper
node_commanalysis -->|"scores"| node_callanalyzer
node_callanalyzer -->|"uses"| node_openai
node_dailybatch -->|"triggers"| node_commanalysis
node_commanalysis -->|"exposes metrics"| node_prometheus
node_marking -->|"reads/writes"| node_bitrix24
node_marking -->|"coordinates"| node_codemanager
node_codemanager -->|"integrates"| node_mdlp
node_codemanager -->|"generates"| node_datamatrix
node_mdlp -->|"connects"| node_gismt
node_marking -->|"exposes metrics"| node_prometheus
node_statusbot -->|"polls"| node_telegram
node_statusbot -->|"reads"| node_bitrix24
node_statusbot -->|"runs"| node_checkorder
node_calculator -->|"uses"| node_calcapi
node_calcapi -->|"creates leads"| node_bitrix24
node_calcapi -.->|"uses"| node_redis
node_analytics -->|"reads"| node_bitrix24
node_analytics -.->|"exposes metrics"| node_prometheus
node_composecore -->|"deploys"| node_webhook
node_composecore -->|"deploys"| node_commanalysis
node_composecore -->|"deploys"| node_marking
node_composecore -->|"deploys"| node_statusbot
node_composecalc -->|"deploys"| node_calculator
node_composemon -->|"deploys"| node_prometheus
node_composemon -->|"deploys"| node_grafana
node_prometheus -->|"feeds"| node_grafana

click node_composecore "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/docker-compose.yml"
click node_composecalc "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/docker-compose.calculator.yml"
click node_composemon "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/docker-compose.monitoring.yml"
click node_prometheus "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/monitoring/prometheus/prometheus.yml"
click node_grafana "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/monitoring/grafana/dashboards/fnr-overview.json"
click node_webhook "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/server.js"
click node_auth "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/middleware/auth.js"
click node_routing "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/services/routing.js"
click node_eventbinder "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/services/eventBinder.js"
click node_commanalysis "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/src/server.js"
click node_whisper "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/src/services/whisper.js"
click node_callanalyzer "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/src/services/callAnalyzer.js"
click node_dailybatch "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/scheduler/dailyBatch.js"
click node_marking "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/server.js"
click node_codemanager "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/services/codeManager.js"
click node_mdlp "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/services/mdlp.js"
click node_datamatrix "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/utils/datamatrix.js"
click node_statusbot "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/fnr-status-bot/src/bot.js"
click node_checkorder "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/fnr-status-bot/src/scenes/checkOrder.js"
click node_calculator "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/calculator/src/App.tsx"
click node_calcapi "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/calculator/server.js"
click node_analytics "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/fnr-analytics/src/App.tsx"
click node_bitrixapi "https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/services/bitrix.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_bitrix24,node_redis,node_lmstudio,node_openai,node_telegram,node_gismt toneBlue
class node_webhook,node_auth,node_routing,node_eventbinder,node_commanalysis,node_whisper,node_callanalyzer,node_dailybatch,node_marking,node_codemanager,node_mdlp,node_datamatrix,node_bitrixapi toneAmber
class node_statusbot,node_checkorder,node_calculator,node_calcapi,node_analytics toneMint
class node_composecore,node_composecalc,node_composemon,node_prometheus,node_grafana toneRose
```

## Components

### External systems

Third-party and local services the repository integrates with

- **Bitrix24**: crm system · System of record for leads, deals, calls, and status data
- **Redis**: state cache · Shared counters, deduplication, and rate limiting state
- **LM Studio**: local llm · Local classification endpoint used by lead routing
- **OpenAI**: ai api · Whisper and GPT-based analysis for call intelligence
- **Telegram**: bot api · Long-polling chat channel for order status lookup
- **GIS MT**: marking system · Честный ЗНАК / MDLP integration boundary

### Control plane

Backend services that ingest Bitrix events and orchestrate automation

- [fnr-webhook](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/server.js): event orchestrator · Bitrix ingress, lead routing, event fan-out, and install flow · `webhook/src/server.js`
- [Auth/rate limit](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/middleware/auth.js): middleware · OAuth validation and request throttling for webhook ingress · `webhook/src/middleware/auth.js`
- [Routing engine](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/services/routing.js): service · Lead classification, manager assignment, and automation decisions · `webhook/src/services/routing.js`
- [Event binder](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/services/eventBinder.js): service · Installs and binds CRM event subscriptions · `webhook/src/services/eventBinder.js`
- [fnr-commanalysis](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/src/server.js): call intelligence · Call transcription, scoring, summaries, and batch reporting · `commanalysis/src/server.js`
- [Transcription](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/src/services/whisper.js): service · Fetches audio and runs Whisper transcription · `commanalysis/src/services/whisper.js`
- [Call analysis](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/src/services/callAnalyzer.js): pipeline · Prompt-driven sentiment, script checks, and data extraction · `commanalysis/src/services/callAnalyzer.js`
- [Daily batch](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/commanalysis/scheduler/dailyBatch.js): scheduler · Cron-style daily summaries and batch execution · `commanalysis/scheduler/dailyBatch.js`
- [fnr-marking](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/server.js): marking integration · CRM-driven marking workflows and DataMatrix generation · `marking/src/server.js`
- [Code manager](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/services/codeManager.js): service · Manages product codes and marking state · `marking/src/services/codeManager.js`
- [MDLP adapter](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/services/mdlp.js): integration · Boundary to marking workflow services and local file state · `marking/src/services/mdlp.js`
- [DataMatrix](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/marking/src/utils/datamatrix.js): utility · Generates printable marking codes · `marking/src/utils/datamatrix.js`
- [Bitrix API client](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/webhook/src/services/bitrix.js): adapter · Shared client layer for CRM reads and writes · `webhook/src/services/bitrix.js`

### User apps

Browser and bot interfaces used by customers and staff

- [fnr-status-bot](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/fnr-status-bot/src/bot.js): telegram bot · Long-polling order status lookup bot · `fnr-status-bot/src/bot.js`
- [Order lookup](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/fnr-status-bot/src/scenes/checkOrder.js): scene · Conversation flow for checking deal or order status · `fnr-status-bot/src/scenes/checkOrder.js`
- [Calculator SPA](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/calculator/src/App.tsx): react app · Customer-facing pricing calculator with Bitrix lead handoff · `calculator/src/App.tsx`
- [Calculator API](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/calculator/server.js): express api · Server-side calculations and Bitrix integration for the calculator · `calculator/server.js`
- [Analytics dashboard](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/fnr-analytics/src/App.tsx): react app · Reporting UI for deals, contacts, managers, and finance · `fnr-analytics/src/App.tsx`

### Operations

Shared deployment and observability stack

- [Core compose](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/docker-compose.yml): deployment stack · Main container stack for backend services · `docker-compose.yml`
- [Calculator compose](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/docker-compose.calculator.yml): deployment stack · Separate stack for the calculator application · `docker-compose.calculator.yml`
- [Monitoring compose](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/docker-compose.monitoring.yml): deployment stack · Stack for metrics collection and dashboards · `docker-compose.monitoring.yml`
- [Prometheus](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/monitoring/prometheus/prometheus.yml): metrics scrape · Scrapes service metrics and monitoring targets · `monitoring/prometheus/prometheus.yml`
- [Grafana](https://github.com/dm1tryandreev1ch/flex-n-roll-pro/blob/main/monitoring/grafana/dashboards/fnr-overview.json): dashboards · Provisioned dashboards for platform visibility · `monitoring/grafana/dashboards/fnr-overview.json`

## Connections

- fnr-webhook → Auth/rate limit: protects · Validates and throttles incoming CRM callbacks
- fnr-webhook → Routing engine: classifies · Dispatches lead automation and manager assignment
- fnr-webhook → Event binder: binds · Manages install-time webhook and event subscriptions
- fnr-webhook → Bitrix API client: calls · Uses Bitrix REST APIs for CRM operations
- Routing engine → LM Studio: asks · Sends lead text to local LLM classification
- Routing engine → Redis: uses · Stores counters and routing state
- Routing engine → Bitrix24: updates · Assigns or updates CRM lead ownership
- fnr-webhook → fnr-commanalysis: forwards · Sends call-related events for analysis
- fnr-commanalysis → Bitrix24: reads · Fetches call metadata and audio from CRM
- fnr-commanalysis → Transcription: transcribes · Runs speech-to-text on call recordings
- fnr-commanalysis → Call analysis: scores · Applies prompt-based sentiment and content checks
- Call analysis → OpenAI: uses · Calls GPT-based analysis services
- Daily batch → fnr-commanalysis: triggers · Runs scheduled batch summaries
- fnr-commanalysis → Prometheus: exposes metrics · Publishes runtime and pipeline metrics
- fnr-marking → Bitrix24: reads/writes · Processes CRM deal updates and marking events
- fnr-marking → Code manager: coordinates · Manages marking codes and product state
- Code manager → MDLP adapter: integrates · Bridges domain operations with marking workflow services
- Code manager → DataMatrix: generates · Creates printable DataMatrix codes
- MDLP adapter → GIS MT: connects · Talks to GIS MT / Честный ЗНАК boundary
- fnr-marking → Prometheus: exposes metrics · Publishes service metrics
- fnr-status-bot → Telegram: polls · Receives updates through the Telegram Bot API
- fnr-status-bot → Bitrix24: reads · Looks up order and deal status in CRM
- fnr-status-bot → Order lookup: runs · Routes the user conversation through a status-check scene
- Calculator SPA → Calculator API: uses · Frontend submits calculations and lead forms to the API
- Calculator API → Bitrix24: creates leads · Hands off calculator submissions into CRM
- Calculator API → Redis: uses · Can share cached or runtime state with backend services
- Analytics dashboard → Bitrix24: reads · Fetches reporting data from CRM
- Analytics dashboard → Prometheus: exposes metrics · Frontend/server observability where applicable
- Core compose → fnr-webhook: deploys · Core backend deployment includes the webhook orchestrator
- Core compose → fnr-commanalysis: deploys · Core backend deployment includes call analysis
- Core compose → fnr-marking: deploys · Core backend deployment includes marking services
- Core compose → fnr-status-bot: deploys · Core backend deployment includes the Telegram bot
- Calculator compose → Calculator SPA: deploys · Calculator stack runs the SPA and API
- Monitoring compose → Prometheus: deploys · Monitoring stack provisions scraping
- Monitoring compose → Grafana: deploys · Monitoring stack provisions dashboards
- Prometheus → Grafana: feeds · Metrics data is visualized in Grafana
