dotfiles/nixos/docs/08-structure.md

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

Как устроена конфигурация.

## Главные файлы

```
flake.nix               - Главная входная точка
configuration.nix       - Системная конфигурация
```

## Папки

```
modules/                - Системные модули
home/ada/               - Конфигурация пользователя (Home Manager)
docs/                   - Документация (этот гайд)
```

## Версионирование

### flake.nix

```nix
inputs = {
  # Откуда берёмся пакеты
  nixpkgs.url = "github:nixos/nixpkgs/nixos-25.11";

  # Управление пользовательским окружением
  home-manager.url = "github:nix-community/home-manager/release-25.11";
};
```

- NixOS версия: **25.11** (стабильный релиз)
- Home Manager версия: **25.11** (синхронизирована)

## Системные модули

### `modules/system/`

Ядро системы:

- **boot.nix** - GRUB загрузчик, kernel modules
- **nix.nix** - Nix конфигурация (flakes, gc, substituters)
- **locale.nix** - Таймзона (Europe/Moscow), системные locale

### `modules/desktop/`

Рабочее окружение:

- **plasma.nix** - KDE Plasma 6, Wayland, X11, раскладка клавиатуры
- **pipewire.nix** - Audio система (PipeWire + ALSA)

### `modules/networking/`

Сетевые сервисы:

- **default.nix** - NetworkManager, Firewall

### `modules/services/`

Системные сервисы:

- **default.nix** - SSH (hardened), Firefox, GnuPG, VPN support

### `modules/users/`

Управление пользователями:

- **ada.nix** - Пользователь `ada` (groups, shell: zsh)

### `modules/virtualisation/`

Виртуализация:

- **virtualbox.nix** - VirtualBox Guest Additions

## Home Manager (Пользователь ada)

### `home/ada/default.nix`

Главный файл (импорты всех модулей):

```nix
home.username = "ada";
home.homeDirectory = "/home/ada";
home.stateVersion = "25.05";
```

### Модули пользователя

| Файл | Назначение |
|------|-----------|
| packages.nix | 50+ пакетов (организованы по категориям) |
| alacritty.nix | Терминальный эмулятор (Nord тема, FiraCode) |
| vim.nix | Vim редактор (Nord тема, плагины) |
| micro.nix | Micro редактор (простой редактор) |
| git.nix | Git конфигурация (15+ алиасов, colors) |
| zsh.nix | ZSH shell (30+ алиасов, интеграции) |
| tmux.nix | Tmux терминальный мультиплексер (VI mode) |
| tools.nix | CLI утилиты (bat, fzf, direnv) |

## Информационный поток

```
flake.nix (входная точка)
    ↓
    ├─→ nixpkgs (версия 25.11)
    ├─→ home-manager (версия 25.11)
    └─→ nixos-hardware

configuration.nix (система)
    ├─→ hardware-configuration.nix
    ├─→ modules/system/* (boot, nix, locale)
    ├─→ modules/desktop/* (plasma, pipewire)
    ├─→ modules/networking/* (network)
    ├─→ modules/services/* (ssh, firefox, etc.)
    ├─→ modules/users/* (пользователь)
    ├─→ modules/virtualisation/* (vbox)
    └─→ Home Manager (через special args)

home/ada/default.nix (пользователь)
    ├─→ packages.nix (50+ пакетов)
    ├─→ alacritty.nix (терминал)
    ├─→ vim.nix (editor)
    ├─→ micro.nix (editor)
    ├─→ git.nix (git config)
    ├─→ zsh.nix (shell)
    ├─→ tmux.nix (multiplexer)
    └─→ tools.nix (utilities)
```

## Категории пакетов

В `packages.nix` пакеты организованы так:

```
Редакторы        vim, neovim, micro
IDE              vscode, idea-community, zed
Терминал         alacritty
Dev tools        tmux, fzf, ripgrep, fd, bat, eza...
Git              git, gh, lazygit
Сеть             curl, wget, ssh, mosh, nmap...
БД               sqlite, postgresql
Утилиты          jq, yq, zip, unzip, gnupg...
Шрифты           nerdfonts (FiraCode)
```

## Какой файл менять?

| Задача | Файл |
|--------|------|
| Добавить переменную окружения | `home/ada/zsh.nix` |
| Добавить программу | `home/ada/packages.nix` |
| Изменить Git конфиг | `home/ada/git.nix` |
| Добавить Shell alias | `home/ada/zsh.nix` |
| Настроить SSH | `modules/services/default.nix` |
| Открыть firewall порт | `modules/networking/default.nix` |
| Добавить язык/locale | `modules/system/locale.nix` |
| Установить новый сервис | Создать новый модуль в `modules/` |
| Конфигурировать программу | Создать новый модуль в `home/ada/` |

## Версия конфигурации

```nix
# configuration.nix
system.stateVersion = "25.05";

# home/ada/default.nix
home.stateVersion = "25.05";

# Обновить можно когда готов к миграции
# Но ОСТОРОЖНО - читай документацию NixOS
```

## Как это всё работает?

1. **flake.nix** - говорит Nix где брать пакеты и как их собрать
2. **configuration.nix** - импортирует все системные модули
3. **modules/** - каждый модуль отвечает за часть системы
4. **home/ada/default.nix** - импортирует все пользовательские модули
5. **home/ada/** - каждый модуль конфигурирует программу

### Когда ты делаешь `nh os switch`:

```
1. Нужно собрать конфигурацию
2. Nix читает flake.nix
3. Понимает что использовать из inputs (nixpkgs, home-manager)
4. Собирает configuration.nix (импортирует все modules/)
5. Собирает home/ada/default.nix через Home Manager
6. Создаёт результат (нов поколение системы)
7. Переключается на него
```

## Быстрая справка

```bash
# Посмотреть версию
cat configuration.nix | grep stateVersion

# Посмотреть импорты
head -30 configuration.nix

# Список всех модулей
ls -la modules/**/*.nix

# Список Home Manager модулей
ls -la home/ada/*.nix

# Найти файл по названию
find . -name "*ssh*"
```

## Следующие шаги

Если хочешь что-то изменить:

1. Найди нужный файл (выше таблица)
2. Отредактируй его
3. Собери: `nh os switch`
4. Если не работает → см. docs/07-troubleshooting.md