FundSync

A Python-based Telegram bot for investment fund reporting and portfolio management.

What is this bot?

This is a secure, multi-user Telegram bot designed for investment fund managers and their investors. It automates fund reporting and communication through Telegram's convenient interface:

• For Fund Admins: Manage multiple users, send portfolio updates, log activities, and send bulk communications
• For Investors: Instantly download personalized PDF reports, view portfolio summaries, and access fund documents—all via Telegram

The bot integrates with Google Sheets (as a data source), generates professional RTL Persian/Arabic PDF reports with proper typography, and maintains a complete audit trail of all activities.

---

Key Features

• Telegram bot built with python-telegram-bot library
• Google Sheets integration (read-only service account authentication)
• PDF report generation with RTL (Right-to-Left) support for Persian/Arabic
• Custom Arabic typography using Noto Sans Arabic fonts
• Admin dashboard with:
  • User management (listing, filtering)
  • Activity logs and summaries
  • Bulk portfolio updates
  • Capital reminder notifications
• User-friendly interface with:
  • Portfolio summary views
  • One-click PDF report downloads
  • Contract and charity fund documents
  • Full activity logging for compliance

---

Architecture

The codebase follows a layered, service-oriented architecture with clear separation of concerns:

• Models Layer - Type-safe domain objects (User, Report, etc.)
• Repository Layer - Data persistence abstraction
• Service Layer - Business logic (SheetService, ReportService, UserService, ActivityService)
• Command Layer - 18 independent command classes for request handling
• Handler Layer - Telegram update routing and dispatch
• Dependency Injection - Centralized via DIContainer

Benefits: Testable, maintainable, extensible, reusable services

---

FundTelegramBot/
├── assets/
│   ├── fonts/
│   │   ├── NotoSansArabic-Regular.ttf
│   │   └── NotoSansArabic-Bold.ttf
│   └── docs/
│       └── contract.pdf
│
├── runtime/
│   ├── bot.log
│   ├── user_data.json
│   ├── chat_ids.json
│   └── snapshots/
│       └── [user wealth history NDJSON files]
│
├── secrets/
│   ├── telegram_bot_token.txt
│   └── fundtelegrambot-xxxx.json
│
├── src/
│   ├── main.py
│   ├── bot/
│   │   ├── app.py
│   │   ├── config.py
│   │   ├── di_container.py
│   │   ├── models/              (User, Report domain models)
│   │   ├── repositories/        (Data access layer)
│   │   ├── services/            (Business logic layer)
│   │   ├── handlers/            (Telegram I/O layer)
│   │   │   └── commands/        (18 independent command classes)
│   │   ├── pdf_report.py
│   │   ├── keyboards.py
│   │   ├── charts_utils.py
│   │   ├── activity_log.py
│   │   └── [utility modules]
│   └── snapshot/
│       ├── job.py
│       ├── build.py
│       ├── storage.py
│       └── parse.py
│
├── installer.sh
├── .gitignore
└── README.md

---

Installation

chmod +x install_dependencies.sh
./install_dependencies.sh

Required Credentials (Secrets Configuration)

Before running the bot, you must populate the secrets/ directory with two files:

1. secrets/telegram_bot_token.txt - Telegram Bot Token

This is your bot's authentication token from Telegram.

How to get it:

1. Open Telegram and search for @BotFather (Telegram's official bot management service)
2. Send /newbot and follow the instructions to create a new bot
3. BotFather will provide you with a token like: 123456789:ABCdefGHIJklmnoPQRstuvwxyz-1234567890
4. Copy this token into secrets/telegram_bot_token.txt (just the token, nothing else)

⚠️ Important: Keep this token secret! Anyone with it can control your bot.

2. secrets/google_service_credentials.json - Google Service Account Credentials

This file allows the bot to read data from your Google Sheets (fund portfolio data).

How to get it:

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Sheets API
4. Go to Service Accounts (under "Credentials")
5. Create a new service account
6. Create a JSON key for the service account
7. Save the downloaded JSON file as secrets/google_service_credentials.json in the secrets/ directory
8. Share your Google Sheet with the service account's email address (found in the JSON file)

⚠️ Important: This JSON file contains credentials. Never commit it to version control (it's already in .gitignore).

Directory Structure After Setup

secrets/
├── telegram_bot_token.txt          (single line: your bot token)
└── google_service_credentials.json (Google service account JSON)

---

Configuration Files (Runtime Data)

Beyond credentials, you must also configure these files with your actual fund data:

1. runtime/user_data.json - User & Investor Registration

This file maps Telegram users to their roles and portfolio data.

What to do:

1. Open runtime/user_data.json
2. Replace the sample data with your actual users
3. For each investor, add:
   • Their Telegram username (without @)
   • Their role ("user" for investors, "admin" for managers)
   • Their name and family name (supports Persian/Arabic)
   • The Google Sheet name containing their portfolio data

Example:

{
  "investor_username": {
    "role": "user",
    "name": "محمد",
    "family": "علی",
    "sheet": "Mohammad"
  },
  "fund_manager": {
    "role": "admin",
    "name": "علی",
    "family": "محمدی"
  }
}

⚠️ Security Note: The sample file has placeholder data. Replace with real user information before deployment.

2. assets/docs/contract.pdf - Fund Investment Contract

This is the PDF contract document that investors can download via the bot.

What to do:

1. Generate or prepare your fund's investment contract/agreement PDF
2. Replace the existing assets/docs/contract.pdf with your actual contract
3. Ensure it's in PDF format
4. The bot will serve this file when investors request the contract

⚠️ Important:

• Use your actual fund contract, not a placeholder
• Ensure all legal text and terms are correct
• Test that the PDF downloads correctly through the bot
• Update this file whenever your contract terms change

---

Running the Bot

Using the startup script (recommended)

./start_bot.sh

Manual execution

source .venv/bin/activate
python src/main.py

---

License

Private / internal use.