3x-ui/docs/maintainer_architecture.md

Maintainer Architecture Notes

Settings

• Authoritative settings storage is now app_settings (single typed row).
• Legacy settings key/value table remains as temporary compatibility fallback.
• SettingService is the single entry point for reads/writes.
• During compatibility window:
  • reads prefer typed storage
  • writes update typed storage and shadow-write legacy key/value rows

Subscription URL Generation

• Canonical URL generation lives in web/service/subscription_urls.go.
• Both flows must use this builder:
  • sub server endpoint rendering (sub/subService.go)
  • Telegram bot subscription links (web/service/tgbot_subscription.go)
• Avoid introducing URL construction logic directly in controllers/services.

Service File Layout

• Large services are split by concern while keeping package boundaries stable.
• web/service/tgbot.go: lifecycle, command handling core.
• web/service/tgbot_subscription.go: subscription link/QR behavior.
• web/service/inbound.go: core inbound CRUD/traffic/migration.
• web/service/inbound_client_mutation.go: repeated client mutation flows.

Web/Sub Listener Bootstrapping

• TLS listener wrapping is centralized in serverutil/listener.go.
• Both web/web.go and sub/sub.go must use it to avoid divergence.

Frontend Path Normalization

• Shared path utilities are in web/assets/js/util/index.js (PathUtil).
• Use PathUtil.normalizePath instead of inline ad-hoc normalization in templates.