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 and setup
  - cache_helpers.go Cache key patterns and TTLs
  - migrations.go Migration runner
  - *_db.go Per-feature database operations
- Directoryi18n/ Internationalization
  - i18n.go Locale embed directive
  - 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
  - …
- Directoryutils/ Utility packages
  - Directoryasync/ Async processing utilities
    …
  - Directorycache/
    cache.go Cache client setup
    adminCache.go Admin cache operations
  - Directorycallbackcodec/ Versioned callback data encoding/decoding
    …
  - Directorychat_status/
    chat_status.go Admin/permission checks
  - Directoryconstants/ Application constants
    …
  - Directoryerror_handling/ Panic recovery and logging
    …
  - Directoryerrors/ Custom error types
    …
  - Directoryextraction/ User/text extraction
    …
  - Directoryhelpers/ General helper functions and decorators
    …
  - Directoryhttpserver/ Unified HTTP server
    …
  - Directorykeyword_matcher/ Keyword matching utilities
    …
  - Directorymedia/ Media handling utilities
    …
  - Directorymonitoring/ Activity and resource monitoring
    …
  - Directoryratelimit/ Rate limiting utilities
    …
  - Directoryshutdown/ Graceful shutdown manager
    …
  - Directorytracing/ OpenTelemetry distributed tracing
    …
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
- Directoryalpine/ Alpine-based Dockerfile
  - …
- Directoryalpine.debug/ Debug variant
  - …
- Directorygoreleaser/ GoReleaser configuration
  - …
- Directorypr-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, justCheck)
chat_status.RequireBotAdmin(b, ctx, chat, justCheck)
chat_status.CanUserRestrict(b, ctx, chat, userId, justCheck)
chat_status.CanBotRestrict(b, ctx, chat, justCheck)
chat_status.CanUserDelete(b, ctx, chat, userId, justCheck)
chat_status.CanBotDelete(b, ctx, chat, justCheck)
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, initializes cache
ResourceMonitor() - Background resource tracking

`alita/config/config.go`

Environment variable parsing:

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

`alita/db/db.go`

Database connection management:

GORM configuration with connection pooling
Auto-migration support
Connection health checking
Graceful connection closing

Module Loading Order

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

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

    modules.LoadBotUpdates(dispatcher)
    modules.LoadAntispam(dispatcher)
    modules.LoadLanguage(dispatcher)
    modules.LoadAdmin(dispatcher)
    modules.LoadPin(dispatcher)
    modules.LoadMisc(dispatcher)
    modules.LoadBans(dispatcher)
    modules.LoadMutes(dispatcher)
    modules.LoadPurges(dispatcher)
    modules.LoadUsers(dispatcher)
    modules.LoadReports(dispatcher)
    modules.LoadDev(dispatcher)
    modules.LoadLocks(dispatcher)
    modules.LoadFilters(dispatcher)
    modules.LoadAntiflood(dispatcher)
    modules.LoadNotes(dispatcher)
    modules.LoadConnections(dispatcher)
    modules.LoadDisabling(dispatcher)
    modules.LoadRules(dispatcher)
    modules.LoadWarns(dispatcher)
    modules.LoadGreetings(dispatcher)
    modules.LoadCaptcha(dispatcher)
    modules.LoadBlacklists(dispatcher)
    modules.LoadReactions(dispatcher)
    modules.LoadMkdCmd(dispatcher)
    modules.LoadBackup(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