📋 Formee - Telegram Form Management Bot

A powerful Telegram bot for managing forms and data collection with Google Sheets integration

🌟 Features

• 📝 Form Management: Create and manage forms through Telegram interface
• 📊 Google Sheets Integration: Seamlessly sync form responses to Google Sheets
• 🔐 Admin System: Super admin functionality for advanced management
• 💾 Local Database: H2 database for fast local data storage
• 🏗️ Clean Architecture: Well-structured codebase following SOLID principles
• 🔄 Real-time Updates: Instant form submission processing

🏛️ Architecture

This project follows Clean Architecture principles with clear separation of concerns:

src/main/kotlin/
├── data/              # Data layer - Database entities and repositories
├── domain/            # Business logic layer
│   ├── model/         # Domain models
│   ├── repository/    # Repository interfaces
│   ├── service/       # Business services
│   └── usecase/       # Use cases
├── infrastructure/    # External services
│   ├── di/            # Dependency injection modules
│   └── sheets/        # Google Sheets integration
└── presentation/      # UI layer
    ├── bot/           # Telegram bot handlers
    ├── controller/    # Controllers
    ├── model/         # Presentation models
    ├── util/          # Utilities
    ├── markdown/      # Markdown formatting
    └── constants/     # Constants

🎯 Architecture Layers

1. Presentation Layer: Handles Telegram bot interactions and user interface
2. Domain Layer: Contains business logic, use cases, and domain models
3. Data Layer: Manages data persistence and repository implementations
4. Infrastructure Layer: Integrates external services (Google Sheets, DI)

🛠️ Technology Stack

Core Technologies

• Language: Kotlin 2.2.0
• JVM: Java 24
• Build Tool: Gradle with Kotlin DSL

Frameworks & Libraries

• Telegram Bot: eu.vendeli.telegram-bot v8.2.0
• Dependency Injection: Koin v4.0.3
• Database ORM: Jetbrains Exposed v0.61.0
• Database: H2 Database v2.2.224
• Google Sheets API: v4-rev20220927-2.0.0
• Authentication: Google Auth Library v1.19.0

Development Tools

• Kotlin Symbol Processing: KSP v2.2.0-2.0.2
• Build Config: GMazzo BuildConfig v5.3.5

🚀 Getting Started

Prerequisites

• Java 24 or higher
• Kotlin 2.2.0 or higher
• Telegram Bot Token (from @BotFather)
• Google Sheets API Credentials

📦 Installation

1. Clone the repository

   git clone <repository-url>
   cd Formee

2. Configure environment variables Create local.properties file:

   TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

3. Setup Google Sheets credentials

   • Place your Google Service Account JSON file as formee-468309-0becfcc54e77.json
   • Ensure the service account has access to your Google Sheets

4. Configure super admins

   • Edit super_admins.csv with authorized admin user IDs

5. Build the project

   ./gradlew build

6. Run the application

   ./gradlew run

⚙️ Configuration

Environment Variables

• TELEGRAM_BOT_TOKEN: Your Telegram bot token from BotFather

Files

• formee-468309-0becfcc54e77.json: Google Service Account credentials
• super_admins.csv: List of super admin user IDs
• local.properties: Local configuration file (not committed to git)

🗄️ Database

The application uses H2 Database for local data storage:

• Database Files: formee_db.mv.db, formee_db.lock.db
• ORM: Jetbrains Exposed for type-safe SQL
• Features: ACID transactions, JSON support, Java Time API integration

📊 Google Sheets Integration

The bot integrates with Google Sheets for data export and synchronization:

• Service Account Authentication: Uses JSON credentials file
• Real-time Sync: Form responses automatically saved to sheets
• API Version: Google Sheets API v4

🤖 Bot Features

For Users

• Interactive form filling
• Real-time validation
• Progress tracking
• Result confirmation

For Admins

• Form creation and management
• Response monitoring
• Data export to Google Sheets
• User management

🏗️ Development

Project Structure

Formee/
├── .gradle/           # Gradle cache
├── .idea/             # IntelliJ IDEA settings
├── .kotlin/           # Kotlin compilation cache
├── build/             # Build outputs
├── gradle/            # Gradle wrapper
├── src/               # Source code
│   ├── main/kotlin/   # Main application code
│   └── test/          # Test code
├── build.gradle.kts   # Build configuration
├── settings.gradle.kts # Gradle settings
└── README.md          # This file

Building from Source

# Clean build
./gradlew clean build

# Run tests
./gradlew test

# Generate build config
./gradlew generateBuildConfig

🧪 Testing

Run the test suite:

./gradlew test

The project uses JUnit Platform for testing with Kotlin test integration.

📝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Follow Kotlin coding conventions
• Use meaningful variable and function names
• Add KDoc comments for public APIs
• Maintain clean architecture principles

🔒 Security

• API Keys: Never commit API keys or tokens to version control
• Service Accounts: Secure your Google Service Account JSON file
• Admin Access: Carefully manage super admin permissions
• Data Privacy: Ensure compliance with data protection regulations

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Support

• Issues: Report bugs and feature requests via GitHub Issues
• Documentation: Check the REFACTORING_SUMMARY.md for recent changes
• Community: Join our community discussions

🎯 Roadmap

• Web dashboard for form management
• Advanced form field types
• Multi-language support
• Analytics and reporting
• Integration with more external services

---

Made with ❤️ using Kotlin and Clean Architecture