soressa-alemayehu/suqredat

"suqredat"is a Telegram-based financial assistant specifically designed for Ethiopian wholesalers to track customer credit, sales, and payments through natural-language conversation. The entire product exists to deliver one core promise: __"Never forget who owes you money again."__ # Never Forget Who Owes You Money A Telegram-based assistant for Ethiopian wholesalers that tracks customer credit, sales, and payments through natural-language conversation. ## Core Promise > **"Never forget who owes you money again."** --- ## Tech Stack * **Runtime**: Node.js 20 LTS + TypeScript (strict mode) * **Messaging**: Telegram Bot API via Telegraf * **AI Parsing**: Google Gemini API (`gemini-2.5-flash` or newer) * **Database**: Supabase (managed PostgreSQL) * **Scheduler**: In-process `node-cron` * **Development Runner**: tsx --- ## Architecture Constraints This project follows a strict non-negotiable rule: **"AI parses. Deterministic code decides."** 1. The AI (Gemini) parses user input to build *draft* data only. It never performs calculations, never makes database writes, and never updates records directly. 2. All balance calculations, ledger entry updates, and SQL writes are handled in plain, deterministic TypeScript code. 3. Every parsed transaction must be explicitly confirmed by the user in Telegram before writing to the database. --- ## Project Structure * `src/bot/` - Telegram controller (handles messaging, routes to services, prompts user confirmation). * `src/ai/` - Gemini parsing service (parses free text into draft objects). * `src/services/` - Deterministic business logic (writes financial records, computes balances). * `src/db/` - Supabase client setup and database queries. * `src/scheduler/` - Cron jobs for automated daily and weekly reporting. --- ## Local Setup & Development 1. **Install dependencies:** ```bash npm install ``` 2. **Configure Environment Variables:** Copy the example environment file and fill in your keys: ```bash cp .env.example .env ``` *Note: Do not commit `.env` containing actual secrets.* 3. **Start Development Server:** ```bash npm run dev ``` This will watch files and restart the bot automatically using `tsx`. 4. **Build Production Code:** ```bash npm run build ``` This compiles TypeScript code to the …