Project Structure

Directory layout and key files in the Alita Robot codebase.

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
alita/ Core application code
- main.go Module loader and initialization
- config/
  - config.go Environment variable parsing
- db/ Database layer
  - db.go GORM connection, setup, and backward-compatible model re-exports
  - conn.go Database connection handle
  - cache/ 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
  - models/ GORM model definitions
  - migrations/ Migration runner
    - runner.go Custom SQL migration engine
  - monitoring/ Database pool metrics
    - metrics.go Metrics collection
  - {domain}/ Per-feature database repositories (admin, antiflood, antiraid, etc.)
    - repository.go Domain-specific DB operations
    - optimized.go Cached SELECT queries (hot reads)
  - backup/ 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)
- i18n/ Internationalization
  - loader.go Locale file loader
  - manager.go Translation manager
  - translator.go Per-request translator
  - types.go Translation types
  - errors.go Error types
- modules/ 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
  - …
- utils/ Utility packages
  - cache/
    - cache.go Cache client setup
    - adminCache.go Admin cache operations
    - restrictedCache.go Restricted chat cache
  - callbackcodec/ Versioned callback data encoding/decoding
  - chat_status/
    - access.go Public permission checks
    - chat_status.go Shared status and membership checks
    - permission_responder.go Permission failure messaging
  - constants/ Application constants
    - time.go Time constants
  - error_handling/ Panic recovery and logging
  - errors/ Custom error types with stack traces
  - extraction/ User/text extraction
  - helpers/ 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
  - content/ Note and filter content extraction
    - content.go Content parsing and validation
  - httpserver/ Unified HTTP server
    - server.go HTTP server
  - keyword_matcher/ Keyword matching utilities
    - matcher.go Pattern matching
  - monitoring/ Activity and resource monitoring
    - activity_monitor.go Activity tracking
    - auto_remediation.go Auto-remediation
    - background_stats.go Background statistics
  - ratelimit/ Rate limiting utilities
    - backup_ratelimit.go Backup rate limiting
  - shutdown/ Graceful shutdown manager
    - graceful.go Graceful shutdown
  - tracing/ OpenTelemetry distributed tracing
  - media/ Media sending utilities
    - sender.go Unified media sender
  - keyboard/ Keyboard building utilities
  - formatting/ HTML/Markdown formatting utilities
migrations/ SQL migration files
- 20250805200527_initial_migration.sql
- …
locales/ 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
docker/ Docker-related files
- alpine Alpine-based Dockerfile
- alpine.debug Debug variant Dockerfile
- goreleaser GoReleaser configuration
- pr-build PR build scripts
docs/ Documentation site (Starlight)
- astro.config.mjs Astro configuration
- src/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:

migrations/
- 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:

# locales/en.yml
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, MESSAGE_DUMP, OWNER_ID (Redis endpoint is required; REDIS_ADDRESS or REDIS_URL)
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 model types (db.User = models.User) and message-type constants (db.TEXT…db.VIDEO_NOTE). Cache helpers and TTL constants live in alita/db/cache/ — they are not re-exported from db.go.

`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 = make(map[string]bool)
    defer modules.LoadHelp(dispatcher)  // Help loaded LAST

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

Next Steps

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