Project Structure

This document explains the directory structure of Alita Robot, helping developers navigate the codebase efficiently.

Directory Tree

main.go Application entry point
AGENTS.md AI assistant guidance document
sample.env Environment variable template
Makefile Build and development commands
go.mod Go module definition
go.sum Go dependency checksums
.goreleaser.yaml Release configuration
Directoryalita/ Core application code
- main.go Module loader and initialization
- Directoryconfig/
  - config.go Environment variable parsing
- Directorydb/ Database layer
  - db.go GORM connection, setup, and backward-compatible cache re-exports
  - conn.go Database connection handle
  - Directorycache/ Cache key patterns, TTLs, and loader
    keys.go CacheKey helper for consistent key formatting
    ttl.go TTL constants
    loader.go GetFromCacheOrLoad with singleflight stampede protection
  - Directorymodels/ GORM model definitions
    …
  - Directorymigrations/ Migration runner
    runner.go Custom SQL migration engine
  - Directorymonitoring/ Database pool metrics
    metrics.go Metrics collection
  - Directoryqueries/ Optimized cached queries
    optimized.go Cached SELECT queries
  - Directory{domain}/ Per-feature database repositories (admin, antiflood, antiraid, etc.)
    repository.go Domain-specific DB operations
  - Directorybackup/ Export/import chat data
    backup.go Module export/import/clear operations
    types.go Backup format structs and validation
- (Locale embed directive is declared in main.go at repository root)
- Directoryi18n/ Internationalization
  - loader.go Locale file loader
  - manager.go Translation manager
  - translator.go Per-request translator
  - types.go Translation types
  - errors.go Error types
- Directorymodules/ Command handlers (features)
  - help.go Help system and module registry
  - bans.go Ban/kick/restrict commands
  - mute.go Mute/unmute commands
  - backup.go Backup/import commands
  - reactions.go Reaction commands
  - filters.go Message filters
  - notes.go Saved notes/messages
  - greetings.go Welcome/goodbye messages
  - warns.go Warning system
  - captcha.go CAPTCHA verification
  - antiraid.go Anti-raid protection
  - antiflood.go Flood detection and control
  - approvals.go User approval system
  - blacklists.go Blacklisted word detection
  - locks.go Permission and restriction locks
  - reports.go User reporting system
  - pins.go Pin management and anti-channel-pin
  - purges.go Message purge commands
  - antispam.go Background antispam watcher
  - connections.go Chat connections from PM
  - disabling.go Command disable management
  - rules.go Group rules management
  - language.go Language configuration
  - formatting.go Message formatting help
  - users.go Automatic user/chat tracking
  - devs.go Developer and sudo commands
  - misc.go Utility commands
  - admin.go Admin promotion and management
  - bot_updates.go Bot join/leave event handler
  - rules_format.go HTML formatting for rules
  - connections_auth.go Connection auth helper
  - callback_codec.go Callback data encoding
  - callback_parse_overwrite.go Callback parsing
  - chat_permissions.go Permission helpers
  - moderation_input.go Text extraction for moderation
  - registry.go Module registration system
  - …
- Directoryutils/ Utility packages
  - Directoryasync/ Async processing utilities
    …
  - Directorycache/
    cache.go Cache client setup
    adminCache.go Admin cache operations
    restrictedCache.go Restricted chat cache
  - Directorycallbackcodec/ Versioned callback data encoding/decoding
    …
  - Directorychat_status/
    chat_status.go Admin/permission checks
    permission_responder.go Permission failure messaging
  - Directoryconstants/ Application constants
    time.go Time constants
  - Directoryerror_handling/ Panic recovery and logging
    …
  - Directoryerrors/ Custom error types with stack traces
    …
  - Directoryextraction/ User/text extraction
    …
  - Directoryhelpers/ General helper functions and decorators
    command_pipeline.go Declarative command pipeline
    decorators.go Command aliases and disableable registration
    telegram_helpers.go Telegram API helpers
    ptr.go Pointer utilities
    test_helper.go Test utilities
  - Directorycontent/ Note and filter content extraction
    content.go Content parsing and validation
  - Directoryhttpserver/ Unified HTTP server
    server.go HTTP server
  - Directorykeyword_matcher/ Keyword matching utilities
    matcher.go Pattern matching
  - Directorymonitoring/ Activity and resource monitoring
    activity_monitor.go Activity tracking
    auto_remediation.go Auto-remediation
    background_stats.go Background statistics
  - Directoryratelimit/ Rate limiting utilities
    backup_ratelimit.go Backup rate limiting
  - Directoryshutdown/ Graceful shutdown manager
    graceful.go Graceful shutdown
  - Directorytracing/ OpenTelemetry distributed tracing
    …
  - Directorymedia/ Media sending utilities
    sender.go Unified media sender
  - Directorykeyboard/ Keyboard building utilities
    …
  - Directoryformatting/ HTML/Markdown formatting utilities
    …
Directorymigrations/ SQL migration files
- 20250805200527_initial_migration.sql
- …
Directorylocales/ Translation files
- en.yml English translations
- es.yml Spanish translations
- fr.yml French translations
- hi.yml Hindi translations
- id.yml Indonesian translations
- pt.yml Portuguese translations
- ru.yml Russian translations
Directorydocker/ Docker-related files
- alpine Alpine-based Dockerfile
- alpine.debug Debug variant Dockerfile
- goreleaser GoReleaser configuration
- pr-build PR build scripts
Directorydocs/ Documentation site (Starlight)
- astro.config.mjs Astro configuration
- Directorysrc/content/docs/ Documentation pages
  - …
- …

`/alita/utils/chat_status/` - Permission Checking Security

Central permission validation:

// Key functions available:
chat_status.RequireUserAdmin(b, ctx, chat, userId)
chat_status.RequireBotAdmin(b, ctx, chat)
chat_status.CanUserRestrict(b, ctx, chat, userId)
chat_status.CanBotRestrict(b, ctx, chat)
chat_status.CanUserDelete(b, ctx, chat, userId)
chat_status.CanBotDelete(b, ctx, chat)
chat_status.IsUserAdmin(b, chatId, userId)
chat_status.IsUserInChat(b, chat, userId)
chat_status.IsUserBanProtected(b, ctx, chat, userId)

`/migrations/` - SQL Migrations Database

Database migrations follow naming convention:

Directorymigrations/
- 20250805200527_initial_migration.sql
- …

Migrations are:

Applied automatically on startup if AUTO_MIGRATE=true
Tracked in schema_migrations table
Idempotent (safe to run multiple times)
Auto-cleaned of Supabase-specific SQL if present

`/locales/` - Translation Files i18n

YAML-based translations:

bans_ban_normal_ban: "Banned %s!"
bans_ban_ban_reason: "\nReason: %s"
bans_kick_kicked_user: "Kicked %s!"
common_no_user_specified: "You need to specify a user!"
chat_status_user_admin_cmd_error: "You need to be an admin to use this command!"

Important Files

`main.go` (Root)

Application entry point handling:

Health check mode (--health flag)
HTTP transport configuration
Dispatcher setup with error handling
Monitoring system initialization
Graceful shutdown coordination
Webhook/polling mode selection

`alita/main.go`

Module loading and initialization:

LoadModules() - Loads all feature modules in order
ListModules() - Returns list of loaded modules
InitialChecks() - Validates configuration and performs startup health checks

`alita/config/config.go`

Environment variable parsing:

Required: BOT_TOKEN, DATABASE_URL, REDIS_ADDRESS, MESSAGE_DUMP, OWNER_ID
Optional: Performance tuning, monitoring, webhooks
Validation and default values

`alita/db/db.go`

Database connection management and backward-compatible re-exports:

GORM configuration with connection pooling
Connection health checking
Graceful connection closing
Re-exports CacheKey and DeleteCache as exported variables; provides getFromCacheOrLoad (lowercase, unexported) as a backward-compatible wrapper; re-exports TTL constants from the cache/ subpackage for convenience

`alita/db/conn.go`

Database connection handle and initialization:

Global DB handle for GORM operations
Connection setup and lifecycle management

Module Loading Order

Modules are loaded in a specific order in alita/main.go:

func LoadModules(dispatcher *ext.Dispatcher) {
    modules.DefaultHelpRegistry().AbleMap.Init()
    defer modules.LoadHelp(dispatcher)  // Help loaded LAST

    // Loads all modules registered via RegisterLegacyModule / RegisterModule
    modules.LoadAllModules(dispatcher)
}

Next Steps

Request Flow - How updates are processed
Module Pattern - Adding new features
Caching - Redis cache architecture

Project Structure

Directory Tree

/alita/utils/chat_status/ - Permission Checking Security

/migrations/ - SQL Migrations Database

/locales/ - Translation Files i18n

Important Files

main.go (Root)

alita/main.go

alita/config/config.go

alita/db/db.go

alita/db/conn.go