# zarnicaclub/zcminiapp architecture

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

## Overview

newCRM ingests Tilda orders and Google Sheets BSO updates, processes emailed call recordings, and presents linked orders, clients, calls, and BSO records in a Telegram Mini App. The main flow is webhook normalization and persistence, plus IMAP parsing/matching and S3 storage; CRM users browse or manually match calls. The graph follows sampled entry points and README capabilities; CRM repository internals and some worker/webhook details are represented only at their supported module paths.

Main entry points: [`orders_webhook/app.py`](https://github.com/zarnicaclub/zcminiapp/blob/main/orders_webhook/app.py) (Webhook routes), [`calls_worker/service.py`](https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/service.py) (Call matching and storage), [`crm/app.py`](https://github.com/zarnicaclub/zcminiapp/blob/main/crm/app.py) (CRM API), [`shared/db.py`](https://github.com/zarnicaclub/zcminiapp/blob/main/shared/db.py) (Database access)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Order intake"]
  node_combined["Application entry<br/>[main.py]"]
  node_webhook["Webhook routes<br/>[app.py]"]
  node_tildaparse["Tilda normalization<br/>[tilda.py]"]
  node_gsparse["BSO normalization<br/>[gsheets.py]"]
  node_ordersvc["Order and BSO upsert<br/>[service.py]"]
  node_mailer["Confirmation email<br/>[mailer.py]"]
end

subgraph group_calls["Call processing"]
  node_worker["Worker scheduler<br/>[main.py]"]
  node_imap["IMAP fetch<br/>[imap.py]"]
  node_parser["Email and MP3 parser<br/>[parser.py]"]
  node_callservice["Call matching and storage<br/>[service.py]"]
end

subgraph group_crm["CRM experience"]
  node_crmapp["CRM API<br/>[app.py]"]
  node_webassets["Mini App assets<br/>[webassets.py]"]
  node_frontend["CRM interface<br/>[app.js]"]
  node_auth["Telegram auth<br/>[auth.py]"]
  node_repo["CRM data access<br/>[repo.py]"]
end

subgraph group_core["Shared services"]
  node_dbpool["Database access<br/>[db.py]"]
  node_postgres[("PostgreSQL")]
  node_s3[("S3 recordings")]
  node_telegramapi["Telegram API"]
  node_smtp["SMTP service"]
end

node_tilda(("Tilda"))
node_gsheets(("Google Apps Script"))
node_mail(("Call email"))
node_telegram(("Telegram user"))

node_telegram -->|"opens Mini App"| node_combined
node_combined -->|"dispatches CRM routes"| node_crmapp
node_combined -->|"dispatches webhook routes"| node_webhook
node_tilda -->|"posts order"| node_webhook
node_gsheets -->|"posts BSO"| node_webhook
node_webhook -->|"parses payload"| node_tildaparse
node_webhook -->|"parses payload"| node_gsparse
node_webhook -->|"upserts records"| node_ordersvc
node_ordersvc -->|"writes orders and clients"| node_dbpool
node_dbpool -->|"queries"| node_postgres
node_ordersvc -.->|"sends confirmation"| node_mailer
node_mailer -.->|"sends email"| node_smtp
node_worker -->|"runs cycles"| node_callservice
node_callservice -->|"fetches messages"| node_imap
node_imap -->|"reads mail"| node_mail
node_callservice -->|"parses and matches"| node_parser
node_callservice -->|"reads orders; writes calls"| node_dbpool
node_callservice -->|"uploads recordings"| node_s3
node_frontend -->|"requests API data"| node_crmapp
node_crmapp -->|"serves assets"| node_webassets
node_crmapp -->|"validates initData"| node_auth
node_crmapp -->|"handles CRM queries"| node_repo
node_repo -->|"reads and updates records"| node_dbpool
node_repo -->|"creates recording links"| node_s3
node_worker -.->|"sends failure alerts"| node_telegramapi

click node_combined "https://github.com/zarnicaclub/zcminiapp/blob/main/app/main.py"
click node_webhook "https://github.com/zarnicaclub/zcminiapp/blob/main/orders_webhook/app.py"
click node_tildaparse "https://github.com/zarnicaclub/zcminiapp/blob/main/shared/tilda.py"
click node_gsparse "https://github.com/zarnicaclub/zcminiapp/blob/main/shared/gsheets.py"
click node_ordersvc "https://github.com/zarnicaclub/zcminiapp/blob/main/orders_webhook/service.py"
click node_mailer "https://github.com/zarnicaclub/zcminiapp/blob/main/shared/mailer.py"
click node_worker "https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/main.py"
click node_imap "https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/imap.py"
click node_parser "https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/parser.py"
click node_callservice "https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/service.py"
click node_crmapp "https://github.com/zarnicaclub/zcminiapp/blob/main/crm/app.py"
click node_webassets "https://github.com/zarnicaclub/zcminiapp/blob/main/crm/webassets.py"
click node_frontend "https://github.com/zarnicaclub/zcminiapp/blob/main/crm/static/app.js"
click node_auth "https://github.com/zarnicaclub/zcminiapp/blob/main/crm/auth.py"
click node_repo "https://github.com/zarnicaclub/zcminiapp/blob/main/crm/repo.py"
click node_dbpool "https://github.com/zarnicaclub/zcminiapp/blob/main/shared/db.py"

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_combined,node_webhook,node_tildaparse,node_gsparse,node_ordersvc,node_mailer,node_telegram toneBlue
class node_worker,node_imap,node_parser,node_callservice toneAmber
class node_crmapp,node_webassets,node_frontend,node_auth,node_repo toneMint
class node_dbpool,node_postgres,node_s3,node_telegramapi,node_smtp toneRose
class node_tilda,node_gsheets,node_mail toneIndigo
```

## Components

### Order intake

- [Application entry](https://github.com/zarnicaclub/zcminiapp/blob/main/app/main.py): `app/main.py`
- [Webhook routes](https://github.com/zarnicaclub/zcminiapp/blob/main/orders_webhook/app.py): `orders_webhook/app.py`
- [Tilda normalization](https://github.com/zarnicaclub/zcminiapp/blob/main/shared/tilda.py): `shared/tilda.py`
- [BSO normalization](https://github.com/zarnicaclub/zcminiapp/blob/main/shared/gsheets.py): `shared/gsheets.py`
- [Order and BSO upsert](https://github.com/zarnicaclub/zcminiapp/blob/main/orders_webhook/service.py): `orders_webhook/service.py`
- [Confirmation email](https://github.com/zarnicaclub/zcminiapp/blob/main/shared/mailer.py): `shared/mailer.py`

### Call processing

- [Worker scheduler](https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/main.py): `calls_worker/main.py`
- [IMAP fetch](https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/imap.py): `calls_worker/imap.py`
- [Email and MP3 parser](https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/parser.py): `calls_worker/parser.py`
- [Call matching and storage](https://github.com/zarnicaclub/zcminiapp/blob/main/calls_worker/service.py): `calls_worker/service.py`

### CRM experience

- [CRM API](https://github.com/zarnicaclub/zcminiapp/blob/main/crm/app.py): `crm/app.py`
- [Mini App assets](https://github.com/zarnicaclub/zcminiapp/blob/main/crm/webassets.py): `crm/webassets.py`
- [CRM interface](https://github.com/zarnicaclub/zcminiapp/blob/main/crm/static/app.js): `crm/static/app.js`
- [Telegram auth](https://github.com/zarnicaclub/zcminiapp/blob/main/crm/auth.py): `crm/auth.py`
- [CRM data access](https://github.com/zarnicaclub/zcminiapp/blob/main/crm/repo.py): `crm/repo.py`

### Shared services

- [Database access](https://github.com/zarnicaclub/zcminiapp/blob/main/shared/db.py): `shared/db.py`
- **PostgreSQL**
- **S3 recordings**
- **Telegram API**
- **SMTP service**

### Other components

- **Tilda**
- **Google Apps Script**
- **Call email**
- **Telegram user**

## Connections

- Telegram user → Application entry: opens Mini App
- Application entry → CRM API: dispatches CRM routes
- Application entry → Webhook routes: dispatches webhook routes
- Tilda → Webhook routes: posts order
- Google Apps Script → Webhook routes: posts BSO
- Webhook routes → Tilda normalization: parses payload
- Webhook routes → BSO normalization: parses payload
- Webhook routes → Order and BSO upsert: upserts records
- Order and BSO upsert → Database access: writes orders and clients
- Database access → PostgreSQL: queries
- Order and BSO upsert → Confirmation email: sends confirmation
- Confirmation email → SMTP service: sends email
- Worker scheduler → Call matching and storage: runs cycles
- Call matching and storage → IMAP fetch: fetches messages
- IMAP fetch → Call email: reads mail
- Call matching and storage → Email and MP3 parser: parses and matches
- Call matching and storage → Database access: reads orders; writes calls
- Call matching and storage → S3 recordings: uploads recordings
- CRM interface → CRM API: requests API data
- CRM API → Mini App assets: serves assets
- CRM API → Telegram auth: validates initData
- CRM API → CRM data access: handles CRM queries
- CRM data access → Database access: reads and updates records
- CRM data access → S3 recordings: creates recording links
- Worker scheduler → Telegram API: sends failure alerts