Sense by Kraliki - Sensitivity Tracking Bot

Formerly SenseIt.

Telegram bot that helps highly sensitive people (HSPs) understand how cosmic, earth, and environmental factors affect their wellbeing. Combines 9 data sources into a unified 0-100 sensitivity score.

When to Use This Skill

• Building or modifying Telegram bot commands (aiogram 3.x)
• Working with cosmic data sources (NOAA space weather, USGS seismic)
• Implementing sensitivity scoring algorithms
• Adding Jungian dream analysis features (Gemini AI)
• Working with biorhythm calculations
• Implementing astrological features (Swiss Ephemeris)
• Adding Telegram Stars payment subscriptions
• Integrating weather data (Open-Meteo)
• Working with Schumann resonance data

Architecture Overview

9 Data Sources → Sensitivity Engine → Unified Score (0-100)
     ↓
User Commands → Telegram Bot → Formatted Reports
     ↓
Premium Features → Telegram Stars Payments

Tech Stack

Data Sources (9 Total)

Max Score: 140 raw points → Normalized to 0-100

Key Components

Bot Handlers (app/bot/handlers.py)

Services (app/services/)

Data Fetchers (app/data/)

Sensitivity Levels

Configuration (.env)

# Required
TELEGRAM_BOT_TOKEN=       # From @BotFather
GEMINI_API_KEY=           # From aistudio.google.com

# Optional
DATABASE_URL=postgresql+asyncpg://localhost/sense_kraliki
REDIS_URL=redis://localhost:6379/0
ADMIN_USER_IDS=123456,789012  # Comma-separated

# Subscription pricing (Telegram Stars)
SENSITIVE_PRICE_STARS=150   # ~$3/mo
EMPATH_PRICE_STARS=350      # ~$7/mo
FREE_DREAMS_PER_MONTH=3

Development

# Navigate to project
cd /home/adminmatej/github/applications/sense-kraliki

# Setup environment
uv sync
source .venv/bin/activate

# Run bot (polling mode)
python -m app.main

# Run with Docker
docker compose up -d

# View logs
docker compose logs -f sense-kraliki-bot

Monetization Model

• Free tier: 3 dream analyses/month, basic sensitivity score
• Sensitive Plan: 150 Stars (~$3/mo) - Unlimited dreams, full breakdowns
• Empath Plan: 350 Stars (~$7/mo) - Everything + 12-month forecasts, personalized remedies

Key Design Decisions

Common Tasks

Add a New Data Source

1. Create fetcher in app/data/new_source.py:

   @dataclass
   class NewSourceData:
       value: float
       sensitivity_score: int  # 0-N contribution
   
   async def get_new_source_data() -> NewSourceData:
       # Fetch and parse data
       pass
   

2. Add to calculate_sensitivity() in app/services/sensitivity.py:

   tasks.append(get_new_source_data())
   # Handle result and add to breakdown
   

3. Update SensitivityBreakdown dataclass with new field

Add a New Command

1. Add handler in app/bot/handlers.py:

   @router.message(Command("newcmd"))
   async def cmd_newcmd(message: Message):
       await analytics.track_command("newcmd", message.from_user.id)
       await message.answer("Response")
   

2. Update /help command text

Modify Dream Analysis Prompt

Edit DREAM_ANALYSIS_PROMPT in app/services/dreams.py. Keep:

• Jungian framework (archetypes, shadow, symbols)
• JSON output format for parsing
• Cosmic context integration

Known Issues (from AUDIT_REPORT.md)

• Critical: Credentials in .env - use secrets manager in production
• High: No .dockerignore - secrets could leak to build context
• Medium: In-memory user state - needs Redis/Postgres persistence
• Medium: No rate limiting on LLM calls - implement quotas

Integration Points

• PM2: Process management via ecosystem.config.js
• Port: 8000 (internal only)
• Blocked by: HW-001 (Telegram bot token creation)

See AUDIT_REPORT.md for security review and recommended fixes