🌱 Satupersen Bot - Daily Reflection Telegram Bot

🇮🇩 Telegram bot refleksi diri harian untuk berkembang 1% setiap hari

Features • Setup • Commands • Deployment • API

📋 Overview

Satupersen adalah Telegram bot canggih yang membantu pengguna melakukan refleksi diri harian dengan bantuan AI. Bot ini menganalisis perkembangan pengguna selama 3 hari terakhir dan memberikan insights, motivasi, serta tracking mood score untuk pertumbuhan personal yang berkelanjutan.

✨ Key Features

🤖 AI-Powered Analysis - Menggunakan Google Gemini Flash untuk analisis refleksi
📊 Mood Score Tracking - Skor suasana hati 1-100 berdasarkan analisis AI
📈 Progress Analytics - Statistik mingguan dan bulanan dengan trend analysis
🔄 3-Day Context - Perbandingan refleksi 3 hari untuk insights yang lebih dalam
🇮🇩 Bahasa Indonesia - Interface dan responses dalam Bahasa Indonesia
🛡️ Enterprise-Grade - Rate limiting, error handling, dan logging komprehensif

🚀 Quick Start

Prerequisites

Installation

Clone repository

git clone https://github.com/underworld14/satupersen-bot.git
cd satupersen-bot

Install dependencies

bun install

Setup environment variables

cp .env.example .env

Edit .env file:

# Bot Configuration
BOT_TOKEN=your_telegram_bot_token_here

# Database
DATABASE_URL=postgresql://username:password@localhost:5432/satupersen

# AI Configuration
GOOGLE_API_KEY=your_google_api_key_here
GOOGLE_AI_MODEL_NAME=gemini-1.5-flash

# Optional: Environment
NODE_ENV=development

Setup database

# Generate Prisma client
bun run db:generate

# Run migrations
bun run db:migrate:dev

Start the bot

# Development mode (with auto-reload)
bun run dev

# Production mode
bun start

🤖 Bot Commands

Command	Description	Usage
`/start`	Memulai bot dan registrasi pengguna	`/start`
`/help`	Menampilkan panduan penggunaan	`/help`
`/reflect`	Input refleksi harian dengan analisis AI	`/reflect`
`/summary`	Ringkasan refleksi hari ini	`/summary`
`/stats`	Statistik refleksi mingguan/bulanan	`/stats`

📱 Interactive Features

Inline Keyboards - Navigasi dengan tombol interaktif
Session Management - Multi-step conversations untuk input refleksi
Callback Handling - Respons cepat untuk aksi pengguna
Error Recovery - Penanganan error yang user-friendly

🏗️ Architecture

satupersen-bot/
├── 📁 docs/              # Project documentation
│   ├── prd.md            # Product Requirements Document
│   └── todo.md           # Development progress tracker
├── 📁 prisma/            # Database schema & migrations
│   ├── schema.prisma     # Database models
│   └── migrations/       # Database migration files
├── 📁 src/               # Source code
│   ├── 📁 commands/      # Bot command handlers
│   │   ├── start-command.ts
│   │   ├── help-command.ts
│   │   ├── reflect-command.ts
│   │   ├── summary-command.ts
│   │   └── stats-command.ts
│   ├── 📁 handlers/      # Centralized callback handlers
│   │   └── callback-handler.ts
│   ├── 📁 middleware/    # Bot middleware
│   │   ├── user-auth.ts
│   │   ├── error-handler.ts
│   │   ├── logging.ts
│   │   └── rate-limiting.ts
│   ├── 📁 services/      # Business logic
│   │   ├── user-service.ts
│   │   ├── reflection-service.ts
│   │   └── analytics-service.ts
│   ├── 📁 types/         # TypeScript definitions
│   └── 📁 utils/         # Helper functions
│       ├── database.ts
│       ├── ai-client.ts
│       ├── env-validation.ts
│       └── message-formatter.ts
├── index.ts              # Application entry point
├── package.json          # Dependencies & scripts
├── Dockerfile            # Container configuration
└── docker-compose.yml    # Multi-service orchestration

💾 Database Schema

User Model

model User {
  id          String        @id @default(uuid())
  telegramId  String        @unique
  username    String?
  firstName   String?
  reflections Reflection[]
  createdAt   DateTime      @default(now())
  updatedAt   DateTime      @updatedAt
}

Reflection Model

model Reflection {
  id         String   @id @default(uuid())
  userId     String
  date       DateTime
  input      String          // User's reflection input
  aiSummary  String?         // AI-generated analysis
  moodScore  Int?            // Mood score (1-100)
  wordCount  Int      @default(0)
  user       User     @relation(fields: [userId], references: [id])
  createdAt  DateTime @default(now())
  updatedAt  DateTime @updatedAt
}

🧠 AI Integration

Google Gemini Flash Integration

Bot menggunakan Google Gemini Flash untuk:

Analisis Refleksi - Menganalisis input pengguna dengan context 3 hari
Mood Score Generation - Menghasilkan skor suasana hati (1-100)
Insight Generation - Memberikan saran dan motivasi personal
Progress Comparison - Membandingkan perkembangan antar hari

AI Prompt Structure

// 3-day reflection context prompt
const prompt = `
Kamu adalah asisten refleksi harian untuk membantuku berkembang 1% setiap hari.

Berikut refleksi saya selama 3 hari:
📅 Dua Hari Lalu: ${twoDaysAgo}
📅 Kemarin: ${yesterday}
📅 Hari Ini: ${today}

Tolong bantu:
1. Ringkasan hari ini
2. Perbandingan perkembangan dari dua hari sebelumnya
3. Hal positif dan yang bisa ditingkatkan
4. Saran untuk hari esok
5. Motivasi singkat
6. moodScore (skor 1-100 berdasarkan analisis sentimen)
`;

📊 Analytics & Statistics

Available Metrics

Reflection Frequency - Berapa sering pengguna melakukan refleksi
Mood Score Trends - Tren perubahan mood score dari waktu ke waktu
Word Count Analysis - Analisis panjang refleksi
Common Themes - Topik yang sering muncul dalam refleksi
Growth Insights - Insights tentang perkembangan personal

Stats Command Output

📊 Statistik Refleksi Mingguan:

🗓 Jumlah hari tercatat: 6 dari 7
😊 Rata-rata moodScore: 75
📈 Tren moodScore: Meningkat
🔥 Kebiasaan dominan: Menulis jurnal, olahraga pagi
💡 Perkembangan: Kamu mulai lebih konsisten
✨ Refleksi terbaik: Hari ke-4
🚀 "Kemajuan kecil setiap hari membangun masa depan luar biasa."

🔧 Development

Available Scripts

# Development
bun run dev              # Start with auto-reload
bun start               # Production start
bun run build           # Build for production

# Database
bun run db:generate     # Generate Prisma client
bun run db:migrate:dev  # Run dev migrations
bun run db:migrate      # Deploy migrations
bun run db:studio       # Open Prisma Studio

# Testing
bun test                # Run all tests
bun test:watch          # Run tests in watch mode

Code Style & Standards

Language: TypeScript dengan strict type checking
Style: ESLint + Prettier configuration
Architecture: Clean Architecture dengan separation of concerns
Testing: Comprehensive unit & integration tests
Documentation: JSDoc untuk public APIs

Contributing

Fork the repository
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

🐳 Deployment

Docker Deployment

Build image

docker build -t satupersen-bot .

Run with Docker Compose

# Start all services (bot + database)
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

Environment for production

NODE_ENV=production
BOT_TOKEN=your_production_bot_token
DATABASE_URL=postgresql://postgres:password@db:5432/satupersen
GOOGLE_API_KEY=your_google_api_key
GOOGLE_AI_MODEL_NAME=gemini-1.5-flash

Manual Deployment

Setup production server

# Install Bun on Ubuntu/Debian
curl -fsSL https://bun.sh/install | bash

# Clone and setup
git clone https://github.com/yourusername/satupersen-bot.git
cd satupersen-bot
bun install

Configure environment

cp .env.example .env
# Edit .env with production values

Setup database

# Run migrations
bun run db:migrate

# Generate client
bun run db:generate

Start with PM2 (recommended)

# Install PM2
bun add -g pm2

# Start bot
pm2 start index.ts --name satupersen-bot --interpreter bun

# Setup auto-restart
pm2 startup
pm2 save

Health Checks

The bot includes built-in health monitoring:

Database Connection - Automatic connection testing on startup
AI API Status - Google Gemini API connectivity check
Graceful Shutdown - Proper cleanup on SIGINT/SIGTERM
Error Recovery - Automatic error handling and user notification

Monitoring

# View bot logs
pm2 logs satupersen-bot

# Monitor performance
pm2 monit

# Restart bot
pm2 restart satupersen-bot

🔐 Security & Best Practices

Security Features

Environment Variables - Secure API key management
Input Validation - Comprehensive input sanitization
Rate Limiting - Protection against spam and abuse
SQL Injection Protection - Prisma ORM with parameterized queries
Error Handling - No sensitive data in error messages

Privacy Considerations

Data Minimization - Only essential user data is stored
Secure Storage - PostgreSQL with proper indexing and relationships
No Logging of Personal Content - Reflections are not logged in application logs

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@satupersen.com
Telegram: @satupersen_support

📄 License

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

🙏 Acknowledgments

Telegraf.js - Modern Telegram Bot Framework
Google Generative AI - Powerful AI capabilities
Prisma - Next-generation ORM
Bun - Fast all-in-one JavaScript runtime
PostgreSQL - Advanced open source database

Made with ❤️ for personal growth and daily reflection

🌱 Start your 1% daily growth journey today

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.cursor		.cursor
.github/workflows		.github/workflows
docs		docs
prisma		prisma
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
bun.lock		bun.lock
docker-compose.yml		docker-compose.yml
index.ts		index.ts
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

🌱 Satupersen Bot - Daily Reflection Telegram Bot

📋 Overview

✨ Key Features

🚀 Quick Start

Prerequisites

Installation

🤖 Bot Commands

📱 Interactive Features

🏗️ Architecture

💾 Database Schema

User Model

Reflection Model

🧠 AI Integration

Google Gemini Flash Integration

AI Prompt Structure

📊 Analytics & Statistics

Available Metrics

Stats Command Output

🔧 Development

Available Scripts

Code Style & Standards

Contributing

🐳 Deployment

Docker Deployment

Manual Deployment

Health Checks

Monitoring

🔐 Security & Best Practices

Security Features

Privacy Considerations

📞 Support

📄 License

🙏 Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages