> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xneon.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Архитектура Xneon Launcher: main, preload, renderer и IPC

> Как устроен Xneon Launcher внутри: процессы Electron, IPC-контракты, воркер запуска Minecraft, SQLite и архитектура скинов через порты.

Xneon Launcher построен на Electron 43 с React 19 и Vite 8. Приложение разделено на три процесса: главный (main), предзагрузчик (preload) и рендерер (renderer). Все тяжелые операции, включая запуск Minecraft, выполняются в отдельном воркере.

## Процессы и их роли

### Главный процесс (main)

Расположен в `electron/main/`. Отвечает за:

* Запуск Minecraft через `minecraft-launch-worker.ts`
* Работу с файловой системой и базой данных SQLite (`data.db`)
* Сетевые запросы к Modrinth, CurseForge, FTB, Laby.net
* Управление серверами (`mc-server:*`)
* Облачную синхронизацию (Google Drive, Dropbox, Яндекс.Диск и др.)
* IPC-обработчики для всех каналов, определенных в `@xnlc/types`

### Preload

Файл `electron/preload.ts` создает безопасный мост между main и renderer. Экспортирует объект `window.electronAPI`, типизированный через `ElectronAPI` из `@xnlc/types`.

### Renderer

React-приложение в `src/` с i18n (`react-i18next`), Tailwind 4 и компонентами из `components/launcher/`.

## IPC-контракты

Все каналы IPC централизованы в `@xnlc/types` (`packages/xnlc-types/src/ipc-contracts.ts`). Это единый источник правды для:

* `IpcInvokeMap`: типы аргументов и возвращаемых значений для вызываемых каналов
* `IpcEventMap`: типы payload для событий (прогресс загрузки, логи сервера и т.д.)
* `ElectronAPI`/`ElectronAPIExplicit`/`ElectronAPIExtra`: полная поверхность API для preload

Добавление нового IPC-канала требует изменений в четырех местах:

<Steps>
  <Step title="Обработчик в main">
    Добавьте обработчик в `electron/main/<feature>/index.ts`
  </Step>

  <Step title="Мост в preload">
    Добавьте вызов в `electron/preload.ts` (window\.electronAPI)
  </Step>

  <Step title="Типизация">
    Добавьте тип в `src/electron.d.ts`
  </Step>

  <Step title="Контракт">
    Добавьте сигнатуру в `packages/xnlc-types/src/ipc-contracts.ts`
  </Step>
</Steps>

## Воркер запуска Minecraft

Запуск игры выполняется в отдельном воркере `electron/main/minecraft-launch-worker.ts`, а не в главном процессе. Это изолирует:

* Долгие операции загрузки активов и библиотек
* Блокирующие вызовы Java
* Потенциальные сбои при запуске

Воркер получает `WorkerLaunchPayload` из `@xnlc/types` и отправляет прогресс через `WorkerMessage`.

## База данных

Локальное хранилище на базе SQLite (`better-sqlite3`) с файлом `data.db`. Поддерживается миграции схемы. Содержит:

* Аккаунты (`DbAccount`)
* Сборки и их контент (`DbBuild`, `DbBuildLight`, `DbBuildMod`)
* Статистику игровых сессий
* Настройки

## Архитектура скинов через порты

Модуль `@xnlc/skins` реализован по принципу портов (ports): логика скинов не зависит от Electron, SQLite или файловой системы. Приложение предоставляет реализацию портов в `electron/main/skins/ports.ts`, а IPC-каналы в `electron/main/skins/index.ts`.

Порты:

* `SkinDiskCache`: кэширование текстур на диск
* `SkinLibraryStore`: хранилище избранных скинов
* `SkinAccountPort`: привязка скинов к аккаунтам

## Структура проекта

```text theme={null}
xneon-launcher/
├── components/launcher/    # React-компоненты
├── electron/
│   ├── main/               # Главный процесс
│   │   ├── minecraft-launch-worker.ts
│   │   ├── skins/
│   │   │   ├── ports.ts
│   │   │   └── index.ts
│   │   └── cloud/
│   ├── preload.ts          # IPC-мост
├── lib/                    # Утилиты
├── packages/               # Модули XNLC
│   ├── xnlc-core/
│   ├── xnlc-mods/
│   ├── xnlc-servers/
│   ├── xnlc-skins/
│   ├── xnlc-nbt/
│   └── xnlc-types/
├── src/                    # Renderer (React + i18n)
│   └── i18n/
├── public/                 # Статика
└── docs/screenshots/       # Скриншоты для документации
```

## Диаграмма архитектуры

```mermaid theme={null}
graph TB
    subgraph Renderer["Renderer Process (React 19)"]
        UI[components/launcher]
        I18N[src/i18n]
    end

    subgraph Preload["Preload Script"]
        API[window.electronAPI]
    end

    subgraph Main["Main Process (Node.js)"]
        IPC[IPC Handlers]
        DB[(SQLite data.db)]
        Worker[Launch Worker]
        Cloud[Cloud Sync]
        Skins[Skins Ports]
    end

    subgraph Packages["XNLC Packages"]
        Core[@xnlc/core]
        Mods[@xnlc/mods]
        Servers[@xnlc/servers]
        SkinsPkg[@xnlc/skins]
        NBT[@xnlc/nbt]
        Types[@xnlc/types]
    end

    UI --> API
    API --> IPC
    IPC --> DB
    IPC --> Worker
    IPC --> Cloud
    IPC --> Skins
    Worker --> Core
    IPC --> Mods
    IPC --> Servers
    Skins --> SkinsPkg
    Core --> Types
    Mods --> Types
    Servers --> Types
    SkinsPkg --> Types
    NBT --> Types
```

<Tip>
  При добавлении нового функционала соблюдайте принцип: вся бизнес-логика остается в main, renderer только отображает данные и отправляет команды через IPC.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.