What Is the Core Module in Amnezia-Client? Architecture and Responsibilities Explained

The core module in amnezia-client (client/core/) serves as the application’s central brain, encapsulating all non-UI business logic, managing the VPN lifecycle, and mediating between the encrypted data layer and the Qt/QML interface.

Located in the client/core/ directory of the amnezia-vpn/amnezia-client repository, this module isolates platform-agnostic VPN operations from presentation concerns. It initializes, owns, and wires together all essential components—from secure repositories to protocol implementations—ensuring the UI layer remains decoupled from underlying cryptographic and network operations.

Central Orchestration: The CoreController

At the heart of the core module lies CoreController, defined in client/core/controllers/coreController.h. This class acts as the single entry point for the entire application, instantiated typically in main.cpp and passed references to the VPN connection engine, secure settings, and the QML application engine.

CoreController creates and retains ownership of all major subsystems:

• m_connectionController – manages active VPN connections
• m_serversRepository – handles encrypted server configuration storage via SecureServersRepository
• m_appSettingsRepository – persists user preferences through SecureAppSettingsRepository
• Protocol implementations – instantiated dynamically based on server selection

The controller exposes high-level actions such as openConnectionByIndex(int index), importConfigFromData(QString data), and updateTranslator(QLocale locale), funneling user intent to specialized sub-controllers while maintaining centralized state.

State Management and Signal Handling

The core module maintains authoritative state for the VPN lifecycle, including the current connection status, selected server index, split-tunneling rules, and localization settings. These values reside as protected members within CoreController (lines 53–95 of coreController.h), accessed through controlled interfaces rather than direct mutation.

Signal propagation is coordinated through CoreSignalHandlers (client/core/controllers/coreSignalHandlers.cpp). The initAllHandlers() method (found in the source implementation) establishes connections between:

• UI controllers emitting user actions
• Repository layers broadcasting data changes
• Platform-specific components (Android/iOS) reporting system events

This decoupled architecture ensures that UI updates, error handling, and background tasks react to state changes without creating circular dependencies between layers.

Data Persistence and Repository Layer

Secure persistence is abstracted behind repository classes within client/core/repositories/:

• SecureServersRepository (secureServersRepository.h/.cpp) – Encrypts and stores server configurations as JSON files
• SecureAppSettingsRepository (secureAppSettingsRepository.h/.cpp) – Manages encrypted user preferences, including credentials and application settings

These repositories implement file-system isolation, ensuring that higher-level components never interact directly with storage mechanisms. Instead, CoreController mediates all read/write operations, providing sanitized data models to the UI layer while handling encryption/decryption transparently.

VPN Protocol Abstraction

All VPN protocol implementations reside under client/core/protocols/, with vpnProtocol.h defining the base interface. The core module instantiates concrete implementations—such as OpenVpnProtocol (openVpnProtocol.h) or WireGuardProtocol (wireGuardProtocol.h)—based on the selected server configuration’s protocol field.

This abstraction allows the CoreController to delegate traffic handling without concerning itself with protocol-specific handshake mechanisms or cryptographic implementations. New protocols can be added by extending the base VpnProtocol class and registering the implementation within the controller’s factory logic.

Platform Integration and UI Context Provisioning

The core module handles platform-specific behaviors through conditional compilation (#ifdef Q_OS_ANDROID, #ifdef Q_OS_IOS) within CoreSignalHandlers.cpp (lines 68–84 and 96–105). This injects platform controllers like AndroidController or IosController without polluting the generic business logic.

For UI integration, CoreController::setQmlRoot() populates the Qt Quick engine with all exposed models and controllers via setQmlContextProperty() (line 46 of coreController.h). This makes core-owned objects accessible to QML while maintaining strict separation—the UI merely displays data provided by the core, never directly manipulating VPN state.

Practical Usage: Interacting with the Core Module

The following examples demonstrate typical interactions with the core module from application code:

Initializing the controller with required dependencies:

auto vpnConnection = QSharedPointer<VpnConnection>::create();
SecureQSettings *settings = new SecureQSettings();
QQmlApplicationEngine *engine = new QQmlApplicationEngine();
CoreController core(vpnConnection, settings, engine);

Establishing a connection by server index:

int serverIndex = 0;                     // Select first server in repository
core.openConnectionByIndex(serverIndex); // Triggers full connection flow via ConnectionController

Importing configuration data securely:

QString ovpnData = "...";                // Raw .ovpn file contents
core.importConfigFromData(ovpnData);    // Validation routed through CoreSignalHandlers

Updating application language at runtime:

QLocale locale(QLocale::French);
core.updateTranslator(locale);           // Signals propagate to all UI components

Each operation flows through CoreController, which delegates to appropriate sub-controllers (e.g., ConnectionController, ImportController) and updates the UI via the signal network established in CoreSignalHandlers.

Summary

• The core module (client/core/) functions as amnezia-client’s central nervous system, separating business logic from UI concerns.
• CoreController orchestrates object lifecycles, maintains VPN state, and exposes the primary API for application features.
• CoreSignalHandlers decouples UI, repositories, and platform components through Qt’s signal/slot mechanism.
• Repository classes provide encrypted persistence abstraction, preventing direct file system access from higher layers.
• Protocol implementations under core/protocols/ enable polymorphic VPN support via the VpnProtocol base class.
• Platform-specific integrations are conditionally compiled into the signal handling layer without affecting core logic portability.

Frequently Asked Questions

What is the difference between CoreController and CoreSignalHandlers?

CoreController owns the objects and state, providing the primary API for actions like connecting or importing configurations, while CoreSignalHandlers wires Qt signals between these objects to ensure UI updates occur reactively. The controller manages what happens; the handlers manage how the system communicates that it happened.

Where does the core module store server configurations?

Server configurations persist through SecureServersRepository (client/core/repositories/secureServersRepository.cpp), which writes encrypted JSON files to the filesystem. The core module abstracts this storage, so UI components interact with in-memory models rather than handling files directly.

How does the core module support multiple VPN protocols?

The module uses polymorphic protocol classes inheriting from VpnProtocol (client/core/protocols/vpnProtocol.h). Based on the selected server’s protocol field, CoreController instantiates the appropriate concrete implementation (e.g., OpenVpnProtocol, WireGuardProtocol), delegating all packet handling to this specialized class while maintaining a uniform interface.

Is the core module platform-specific?

No, the core logic remains platform-agnostic. Platform-specific code is isolated via conditional compilation (found in CoreSignalHandlers.cpp lines 68–105) and injected only when compiling for Android or iOS. This allows the majority of the core module code to remain portable across desktop and mobile targets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}