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

> Discover the Amnezia-Client core module. Learn how it manages the VPN lifecycle and bridges data layers with the Qt/QML interface. Understand its architecture and responsibilities.

- Repository: [Amnezia VPN/amnezia-client](https://github.com/amnezia-vpn/amnezia-client)
- Tags: internals
- Published: 2026-07-29

---

**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](https://github.com/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/client/core/controllers/coreController.h). This class acts as the single entry point for the entire application, instantiated typically in [`main.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/coreController.h)), accessed through controlled interfaces rather than direct mutation.

Signal propagation is coordinated through **`CoreSignalHandlers`** ([`client/core/controllers/coreSignalHandlers.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/secureServersRepository.h/.cpp)) – Encrypts and stores server configurations as JSON files
- **`SecureAppSettingsRepository` ([`secureAppSettingsRepository.h/.cpp`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/vpnProtocol.h) defining the base interface. The **core module** instantiates concrete implementations—such as `OpenVpnProtocol` ([`openVpnProtocol.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/openVpnProtocol.h)) or `WireGuardProtocol` ([`wireGuardProtocol.h`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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:

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

```

Establishing a connection by server index:

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

```

Importing configuration data securely:

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

```

Updating application language at runtime:

```cpp
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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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`](https://github.com/amnezia-vpn/amnezia-client/blob/main/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.