How bahadirkayra/alfasystonl works
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 Supabase · README.md Panel Sources · volume.ts Worker Jobs · DeliveriesView.tsx Business Views
Components 21
Frontend
Vite + React single-page app and shared client data access.
- Entry · Bootstraps the React application.
index.tsx - App · Top-level application routing and screen composition.
App.tsx - Sidebar · Primary navigation for the business views.
components/Sidebar.tsx - Business Views · Main operational screens for reconciliation, deliveries, reports, and management.
components/DeliveriesView.tsx - Supabase Client · Client-side Supabase access used by the SPA.
services/supabase.ts - Mock 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 · Delivery sync and latest-row endpoints plus Telegram test hook.
api/deliveries/sync.ts - Volume API · Syncs volume snapshots from panel sources into Supabase.
api/volume/sync.ts - Withdrawals API · Handles withdrawal search, sync, and dekont retrieval.
api/withdrawals/sync.ts - Subcontractors API · Syncs subcontractor state and emits status notifications.
api/subcontractors/sync.ts - Mutabakat API · Writes reconciliation snapshots and control rows.
api/mutabakat/sync.ts - Investment Search · Panel-id lookup used by investment and withdrawal screens.
api/investments/search.ts - Telegram Webhook · Bot commands, chat registration, role-based messaging, and callbacks.
api/telegram/webhook.ts - Telegram Admin · Webhook setup and bot administration utilities.
api/telegram/set-webhook.ts - Telegram Automations · 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 · Long-running worker entrypoint and HTTP surface.
workers/index.ts - Worker Jobs · Scheduled ingestion, maintenance, and dashboard sync jobs.
workers/jobs/volume.ts - Worker Lib · Environment, locks, logging, scheduler, panel, Supabase, and Telegram helpers.
workers/lib/scheduler.ts
State & Integrations
Supabase/Postgres plus external panel and Telegram systems.
- Supabase · System of record, realtime fan-out, and bot state storage.
supabase.sql - Panel Sources · External Alfa/Mars-style systems scraped by API routes and workers.
README.md - Telegram · Outbound notifications and bot command channel.
Connections 27
- 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.