# bahadirkayra/alfasystonl architecture

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

- Interactive diagram: https://gitdiagram.com/bahadirkayra/alfasystonl
- Repository: https://github.com/bahadirkayra/alfasystonl

## Overview

1. **Overall shape**
   - This repo is a **Vite + React SPA** on the front end, backed by **Vercel serverless API routes** and a separate **Node worker process**.  
   - **Supabase/Postgres** is the system of record: the UI mostly reads from Supabase, while API routes and workers pull data from external panels, transform it, and upsert it into Supabase.  
   - **Telegram** is the main outbound channel for notifications and bot commands.

2. **Frontend boundary**
   - `index.tsx`, `App.tsx`, and `components/*` form the single-page application.
   - The app is organized into business views such as **Mutabakat**, **Teslimat**, **Hacim Raporu**, **Çekim Y.**, **Taşeronlar**, **Bot Yönetimi**, **Kasa**, and reporting/management screens.
   - The UI is not the source of truth for these datasets; it consumes **DB snapshots** and realtime updates via `services/supabase.ts`.

3. **Client-side data access**
   - `services/supabase.ts` provides the Supabase client used by the UI.
   - `services/mockData.ts` suggests a fallback/demo data path for local development or non-connected states.
   - The UI also calls Vercel endpoints when it needs to trigger syncs or panel fetches, but the live views are designed to read from Supabase rather than directly from the remote panels.

4. **Serverless integration layer**
   - The `api/` folder is the main boundary between the app and external systems.
   - It contains dedicated endpoints for each business process:  
     - `mutabakat/sync`  
     - `subcontractors/sync` and `subcontractors/status-notify`  
     - `volume/sync`  
     - `deliveries/sync`, `deliveries/latest`, `deliveries/test-telegram`  
     - `investments/search`  
     - `withdrawals/search`, `withdrawals/sync`, `withdrawals/dekont`  
     - Telegram routes under `api/telegram/*`
   - These endpoints are auth-protected with a mix of **Supabase bearer auth** and **secret headers/query params**, so the UI, cron jobs, and bots all hit the same backend contracts.

5. **External panel ingestion**
   - The repo integrates with one or more external “panel” systems through configurable URLs, paths, and session cookies.
   - The readme makes the two main sources explicit: **Alfa** and **Mars**.
   - The API layer and worker jobs scrape panel pages/AJAX endpoints, normalize row data, and store it in Postgres tables like `deliveries`, `withdrawals_high`, `volume_snapshots`, `mars_volume_snapshots`, and reconciliation tables.
   - This is an **ETL-style architecture**: scrape → normalize → upsert → UI/realtime/Telegram consumption.

6. **Domain pipelines**
   - **Deliveries**: syncs new incoming delivery records, exposes latest rows for the bot, and can emit Telegram notifications.
   - **Volume**: syncs site-based investment/withdrawal/total-difference metrics, with separate storage for Alfa vs Mars snapshots.
   - **Withdrawals**: filters for approved high-value withdrawals and stores them in `withdrawals_high`.
   - **Subcontractors**: syncs subcontractor status and panel IDs, and can notify Telegram on active/passive transitions.
   - **Mutabakat**: reads configured reconciliation targets and writes snapshot/control rows so all users see the same reconciled state.
   - **Investments/Search**: panel-id lookup endpoints used by the investment and withdrawal screens.

7. **Telegram subsystem**
   - Telegram is treated as a first-class integration, not just an alert channel.
   - `api/telegram/webhook.ts` handles bot commands such as status queries, reporting commands, chat registration, broadcast/role-based messaging, and subcontractor status commands.
   - `api/telegram/set-webhook.ts` manages webhook setup and bot admin operations.
   - `api/telegram/auto-hacim.ts` automates periodic volume posting, while `api/telegram/auto-gunsonu-kasa.ts` supports end-of-day cash automation.
   - Bot state, access requests, allowed chats, shortcuts, and roles are persisted in Supabase tables, so bot behavior is centrally managed.

8. **Worker/runtime subsystem**
   - `workers/` is a separate long-running process layer for scheduled/background work.
   - `workers/index.ts` and `workers/httpServer.ts` suggest a worker runtime with an HTTP surface plus internal scheduling.
   - `workers/jobs/*` contains task-specific jobs such as deliveries, subcontractors, volume, withdrawals, telegram digest/maintenance/outbox, recent dashboard sync, shadow queue handling, and pool-ticket cleanup/recovery.
   - `workers/lib/*` provides shared plumbing: env loading, logging, scheduling, locks, panel access, Supabase access, and Telegram helpers.
   - The lock module indicates the jobs are designed to avoid duplicate concurrent runs.

9. **Database as shared state and realtime bus**
   - The SQL files define the schema and cron support in Supabase, including reconciliation tables, contractor sync control, telegram access tables, and delivery/volume/withdrawal structures.
   - The UI’s live views rely on **Supabase realtime** so that new sync results appear without extra API calls.
   - This makes Supabase both the **storage layer** and the **fan-out mechanism** for dashboards and bot-visible data.

10. **Operational model**
   - The repo is built for **serverless hosting on Vercel** plus **Supabase cron** for periodic calls.
   - Environment variables control panel credentials, Telegram bot credentials, secrets for cron/API calls, and per-channel chat IDs.
   - Several migration/repair SQL files show that operational recovery is a normal part of the architecture: schema migration, cron repair, and job auditing are explicit concerns.
   - `vercel.json`, `vite.config.ts`, `ecosystem.config.cjs`, and the Supabase SQL scripts together define how the app is deployed, scheduled, and kept consistent across domains.

11. **Primary architectural boundary to draw**
   - A useful diagram would place **React UI** on one side, **Vercel API + Telegram webhook** in the middle, and **Supabase/Postgres + external panel systems + Telegram** on the other side.
   - Background **workers/cron** should be shown as a parallel ingestion/maintenance path that also writes into Supabase and Telegram, independent from the user-driven UI path.

Main entry points: [`supabase.sql`](https://github.com/bahadirkayra/alfasystonl/blob/main/supabase.sql) (Supabase), [`README.md`](https://github.com/bahadirkayra/alfasystonl/blob/main/README.md) (Panel Sources), [`workers/jobs/volume.ts`](https://github.com/bahadirkayra/alfasystonl/blob/main/workers/jobs/volume.ts) (Worker Jobs), [`components/DeliveriesView.tsx`](https://github.com/bahadirkayra/alfasystonl/blob/main/components/DeliveriesView.tsx) (Business Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_index["Entry<br/>[index.tsx]"]
  node_app["App<br/>spa shell<br/>[App.tsx]"]
  node_sidebar["Sidebar<br/>nav shell<br/>[Sidebar.tsx]"]
  node_views["Business Views<br/>ui screens<br/>[DeliveriesView.tsx]"]
  node_supabase_client[("Supabase Client<br/>db client<br/>[supabase.ts]")]
  node_mock_data["Mock Data<br/>fallback data<br/>[mockData.ts]"]
end

subgraph group_api["Vercel API"]
  node_deliveries_api["Deliveries API<br/>sync endpoints<br/>[sync.ts]"]
  node_volume_api["Volume API<br/>sync endpoint<br/>[sync.ts]"]
  node_withdrawals_api["Withdrawals API<br/>search/sync<br/>[sync.ts]"]
  node_subcontractors_api["Subcontractors API<br/>sync/notify<br/>[sync.ts]"]
  node_mutabakat_api["Mutabakat API<br/>reconcile sync<br/>[sync.ts]"]
  node_investments_api["Investment Search<br/>lookup endpoint<br/>[search.ts]"]
  node_telegram_webhook["Telegram Webhook<br/>bot ingress<br/>[webhook.ts]"]
  node_telegram_admin["Telegram Admin<br/>bot setup<br/>[set-webhook.ts]"]
  node_telegram_auto["Telegram Automations<br/>bot jobs<br/>[auto-hacim.ts]"]
end

subgraph group_workers["Workers"]
  node_worker_main["Worker Main<br/>runtime<br/>[index.ts]"]
  node_worker_jobs["Worker Jobs<br/>job pipeline<br/>[volume.ts]"]
  node_worker_lib["Worker Lib<br/>shared plumbing<br/>[scheduler.ts]"]
end

subgraph group_data["State & Integrations"]
  node_supabase[("Supabase<br/>postgres + realtime<br/>[supabase.sql]")]
  node_panel_sources["Panel Sources<br/>external panels<br/>[README.md]"]
  node_telegram(("Telegram<br/>messaging platform"))
end

node_index -->|"mounts"| node_app
node_app -->|"navigates"| node_sidebar
node_app -->|"renders"| node_views
node_views -->|"reads live data"| node_supabase_client
node_views -.->|"fallback"| node_mock_data
node_deliveries_api -->|"scrapes"| node_panel_sources
node_deliveries_api -->|"upserts"| node_supabase
node_volume_api -->|"scrapes"| node_panel_sources
node_volume_api -->|"upserts"| node_supabase
node_withdrawals_api -->|"scrapes"| node_panel_sources
node_withdrawals_api -->|"upserts"| node_supabase
node_subcontractors_api -->|"scrapes"| node_panel_sources
node_subcontractors_api -->|"upserts"| node_supabase
node_mutabakat_api -->|"writes"| node_supabase
node_investments_api -->|"looks up"| node_panel_sources
node_telegram_webhook -->|"receives commands"| node_telegram
node_telegram_webhook -->|"reads/writes state"| node_supabase
node_telegram_admin -->|"configures"| node_telegram
node_telegram_auto -->|"posts updates"| node_telegram
node_worker_main -->|"loads"| node_worker_lib
node_worker_jobs -->|"scrapes"| node_panel_sources
node_worker_jobs -->|"upserts"| node_supabase
node_worker_jobs -->|"notifies"| node_telegram
node_worker_jobs -->|"uses"| node_worker_lib
node_supabase -->|"realtime fan-out"| node_views
node_supabase -->|"bot state"| node_telegram_webhook
node_supabase -->|"job state"| node_worker_jobs

click node_index "https://github.com/bahadirkayra/alfasystonl/blob/main/index.tsx"
click node_app "https://github.com/bahadirkayra/alfasystonl/blob/main/App.tsx"
click node_sidebar "https://github.com/bahadirkayra/alfasystonl/blob/main/components/Sidebar.tsx"
click node_views "https://github.com/bahadirkayra/alfasystonl/blob/main/components/DeliveriesView.tsx"
click node_supabase_client "https://github.com/bahadirkayra/alfasystonl/blob/main/services/supabase.ts"
click node_mock_data "https://github.com/bahadirkayra/alfasystonl/blob/main/services/mockData.ts"
click node_deliveries_api "https://github.com/bahadirkayra/alfasystonl/blob/main/api/deliveries/sync.ts"
click node_volume_api "https://github.com/bahadirkayra/alfasystonl/blob/main/api/volume/sync.ts"
click node_withdrawals_api "https://github.com/bahadirkayra/alfasystonl/blob/main/api/withdrawals/sync.ts"
click node_subcontractors_api "https://github.com/bahadirkayra/alfasystonl/blob/main/api/subcontractors/sync.ts"
click node_mutabakat_api "https://github.com/bahadirkayra/alfasystonl/blob/main/api/mutabakat/sync.ts"
click node_investments_api "https://github.com/bahadirkayra/alfasystonl/blob/main/api/investments/search.ts"
click node_telegram_webhook "https://github.com/bahadirkayra/alfasystonl/blob/main/api/telegram/webhook.ts"
click node_telegram_admin "https://github.com/bahadirkayra/alfasystonl/blob/main/api/telegram/set-webhook.ts"
click node_telegram_auto "https://github.com/bahadirkayra/alfasystonl/blob/main/api/telegram/auto-hacim.ts"
click node_worker_main "https://github.com/bahadirkayra/alfasystonl/blob/main/workers/index.ts"
click node_worker_jobs "https://github.com/bahadirkayra/alfasystonl/blob/main/workers/jobs/volume.ts"
click node_worker_lib "https://github.com/bahadirkayra/alfasystonl/blob/main/workers/lib/scheduler.ts"
click node_supabase "https://github.com/bahadirkayra/alfasystonl/blob/main/supabase.sql"
click node_panel_sources "https://github.com/bahadirkayra/alfasystonl/blob/main/README.md"

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_index,node_app,node_sidebar,node_views,node_supabase_client,node_mock_data toneBlue
class node_deliveries_api,node_volume_api,node_withdrawals_api,node_subcontractors_api,node_mutabakat_api,node_investments_api,node_telegram_webhook,node_telegram_admin,node_telegram_auto toneAmber
class node_worker_main,node_worker_jobs,node_worker_lib toneMint
class node_supabase,node_panel_sources,node_telegram toneRose
```

## Components

### Frontend

Vite + React single-page app and shared client data access.

- [Entry](https://github.com/bahadirkayra/alfasystonl/blob/main/index.tsx): spa entry · Bootstraps the React application. · `index.tsx`
- [App](https://github.com/bahadirkayra/alfasystonl/blob/main/App.tsx): spa shell · Top-level application routing and screen composition. · `App.tsx`
- [Sidebar](https://github.com/bahadirkayra/alfasystonl/blob/main/components/Sidebar.tsx): nav shell · Primary navigation for the business views. · `components/Sidebar.tsx`
- [Business Views](https://github.com/bahadirkayra/alfasystonl/blob/main/components/DeliveriesView.tsx): ui screens · Main operational screens for reconciliation, deliveries, reports, and management. · `components/DeliveriesView.tsx`
- [Supabase Client](https://github.com/bahadirkayra/alfasystonl/blob/main/services/supabase.ts): db client · Client-side Supabase access used by the SPA. · `services/supabase.ts`
- [Mock Data](https://github.com/bahadirkayra/alfasystonl/blob/main/services/mockData.ts): fallback data · Local/demo data path for disconnected or development states. · `services/mockData.ts`

### Vercel API

Serverless integration layer for syncs, searches, Telegram webhooks, and admin actions.

- [Deliveries API](https://github.com/bahadirkayra/alfasystonl/blob/main/api/deliveries/sync.ts): sync endpoints · Delivery sync and latest-row endpoints plus Telegram test hook. · `api/deliveries/sync.ts`
- [Volume API](https://github.com/bahadirkayra/alfasystonl/blob/main/api/volume/sync.ts): sync endpoint · Syncs volume snapshots from panel sources into Supabase. · `api/volume/sync.ts`
- [Withdrawals API](https://github.com/bahadirkayra/alfasystonl/blob/main/api/withdrawals/sync.ts): search/sync · Handles withdrawal search, sync, and dekont retrieval. · `api/withdrawals/sync.ts`
- [Subcontractors API](https://github.com/bahadirkayra/alfasystonl/blob/main/api/subcontractors/sync.ts): sync/notify · Syncs subcontractor state and emits status notifications. · `api/subcontractors/sync.ts`
- [Mutabakat API](https://github.com/bahadirkayra/alfasystonl/blob/main/api/mutabakat/sync.ts): reconcile sync · Writes reconciliation snapshots and control rows. · `api/mutabakat/sync.ts`
- [Investment Search](https://github.com/bahadirkayra/alfasystonl/blob/main/api/investments/search.ts): lookup endpoint · Panel-id lookup used by investment and withdrawal screens. · `api/investments/search.ts`
- [Telegram Webhook](https://github.com/bahadirkayra/alfasystonl/blob/main/api/telegram/webhook.ts): bot ingress · Bot commands, chat registration, role-based messaging, and callbacks. · `api/telegram/webhook.ts`
- [Telegram Admin](https://github.com/bahadirkayra/alfasystonl/blob/main/api/telegram/set-webhook.ts): bot setup · Webhook setup and bot administration utilities. · `api/telegram/set-webhook.ts`
- [Telegram Automations](https://github.com/bahadirkayra/alfasystonl/blob/main/api/telegram/auto-hacim.ts): bot jobs · Scheduled Telegram posting for hacim and end-of-day cash flows. · `api/telegram/auto-hacim.ts`

### Workers

Background runtime for scheduled ingestion, maintenance, and Telegram automation.

- [Worker Main](https://github.com/bahadirkayra/alfasystonl/blob/main/workers/index.ts): runtime · Long-running worker entrypoint and HTTP surface. · `workers/index.ts`
- [Worker Jobs](https://github.com/bahadirkayra/alfasystonl/blob/main/workers/jobs/volume.ts): job pipeline · Scheduled ingestion, maintenance, and dashboard sync jobs. · `workers/jobs/volume.ts`
- [Worker Lib](https://github.com/bahadirkayra/alfasystonl/blob/main/workers/lib/scheduler.ts): shared plumbing · Environment, locks, logging, scheduler, panel, Supabase, and Telegram helpers. · `workers/lib/scheduler.ts`

### State & Integrations

Supabase/Postgres plus external panel and Telegram systems.

- [Supabase](https://github.com/bahadirkayra/alfasystonl/blob/main/supabase.sql): postgres + realtime · System of record, realtime fan-out, and bot state storage. · `supabase.sql`
- [Panel Sources](https://github.com/bahadirkayra/alfasystonl/blob/main/README.md): external panels · External Alfa/Mars-style systems scraped by API routes and workers. · `README.md`
- **Telegram**: messaging platform · Outbound notifications and bot command channel.

## Connections

- Entry → App: mounts · Bootstraps the SPA shell.
- App → Sidebar: navigates · Delegates screen switching to the main navigation.
- App → Business Views: renders · Composes the operational business screens.
- Business Views → Supabase Client: reads live data · Views consume snapshots and realtime updates from Supabase.
- Business Views → Mock Data: fallback · Uses demo/local data when connected state is unavailable.
- Deliveries API → Panel Sources: scrapes · Fetches delivery records from external panels.
- Deliveries API → Supabase: upserts · Stores normalized delivery rows in Postgres.
- Volume API → Panel Sources: scrapes · Pulls site metrics from external panel endpoints.
- Volume API → Supabase: upserts · Persists volume snapshots for UI and bot consumption.
- Withdrawals API → Panel Sources: scrapes · Looks up and syncs withdrawal-related panel data.
- Withdrawals API → Supabase: upserts · Stores high-value withdrawal records and related rows.
- Subcontractors API → Panel Sources: scrapes · Reads subcontractor status and identifiers from panels.
- Subcontractors API → Supabase: upserts · Persists subcontractor status and notification state.
- Mutabakat API → Supabase: writes · Updates reconciliation snapshots and controls.
- Investment Search → Panel Sources: looks up · Queries panel-side identifiers for search screens.
- Telegram Webhook → Telegram: receives commands · Handles bot messages, callbacks, and chat registration.
- Telegram Webhook → Supabase: reads/writes state · Uses stored roles, chats, and access state.
- Telegram Admin → Telegram: configures · Manages webhook setup and bot administration.
- Telegram Automations → Telegram: posts updates · Sends scheduled hacim and cash automation messages.
- Worker Main → Worker Lib: loads · Starts worker runtime services and shared plumbing.
- Worker Jobs → Panel Sources: scrapes · Background jobs ingest and normalize panel data.
- Worker Jobs → Supabase: upserts · Writes job results into shared Postgres state.
- Worker Jobs → Telegram: notifies · Emits digests, outbox messages, and maintenance alerts.
- Worker Jobs → Worker Lib: uses · Relies on locks, scheduler, auth, and transport helpers.
- Supabase → Business Views: realtime fan-out · Feeds live dashboards and status screens.
- Supabase → Telegram Webhook: bot state · Persists chat, role, and automation state.
- Supabase → Worker Jobs: job state · Shares queues, snapshots, and maintenance metadata.
