--- title: Project Structure description: 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 shared-load 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 - aispam.go Per-chat AI spam filter (TypeSafe Jev) - aispam_jev.go Jev client for the AI spam filter - spamdb.go Per-chat CAS and lols.bot spam database check on join - 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 handler, admin-cache refresh, anonymous-admin verification - 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 - actionlog/ Moderation action entries sent to the chat's log channel - 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 - logredact/ Secret redaction for log output (register secrets with `logredact.RegisterSecret`) - metrics/ Prometheus metric definitions - 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 - updatememo/ Values memoised for one update (backs the `*ForUpdate` predicates) - 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 - ... - internal/ - testdb/ SQLite test database harness (`testdb.Run`) - scripts/ Docs generator, translation checker, test-result gate, migrate_psql.sh, bump_version.sh, backup_database.sh - 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 (Blume)** - blume.config.ts Blume configuration - src/content/docs/ Documentation pages - ... ### `/alita/utils/chat_status/` - Permission Checking Security Central permission validation: ```go // 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: ```yaml # 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!" ``` :::note[Translation key conventions] - Use double quotes for strings with escape sequences (`\n`, `\t`) - Use `%s`, `%d` for formatting placeholders - Prefix keys with module name for organization - Always add keys to ALL locale files, not just `en.yml` ::: ## 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()` - Ensures the bot's own user row exists in the database (`user.EnsureBotInDb`) ### `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`: ```go func LoadModules(dispatcher *ext.Dispatcher) { modules.ResetHelpRegistry() defer modules.LoadHelp(dispatcher) // Help loaded LAST // Loads all modules registered via RegisterLegacyModule modules.LoadAllModules(dispatcher) } ``` :::note[Why order matters] - **Priority-based loading**: Modules self-register in `init()` with a priority; `LoadAllModules` sorts them before loading - **Dependency resolution**: Lower priority numbers load first (e.g., Bans at 70 before Users at 100) - **Help module**: Loads last via `defer` to collect all registered commands from every module ::: ## Next Steps - [Request Flow](/architecture/request-flow) - How updates are processed - [Module Pattern](/architecture/module-pattern) - Adding new features - [Caching](/architecture/caching) - Redis cache architecture