radar_system/python_app/docs/architecture_overview.md

Архитектурный обзор Python-части

1. Верхнеуровневая схема

Python-часть разделена на следующие пакеты:

• gui: desktop UI на PyQt6 + pyqtgraph.
• models: dataclass-модели runtime-конфига и датасетов.
• orchestration: управление runtime-конфигом, процессами и SHM-ридерами.
• storage: persistent storage для calibration/reference и runtime snapshots.
• hardware_full: Python-обертки над LibreVNA и switch drivers.
• workflows: сценарии калибровки/референса/последовательного захвата.
• scripts: эксплуатационные и отладочные скрипты.

2. Ключевые архитектурные решения

• GUI оставлен единой точкой входа (AppWindow), но тяжелая логика вынесена в sections, plotting и runtime helpers.
• Конфиг разделен на schema/codec/validation:
  • run_config_schema.py
  • run_config_codec.py
  • run_config_validation.py
  • run_config_model.py как фасадный модуль.
• Storage разделен на подпакет storage/npz/*:
  • paths.py
  • serialize.py
  • snapshot_numpy.py
  • store.py
• SHM-декодирование разделено на orchestration/shm/*:
  • binary_cursor.py
  • decoder.py
  • ring_reader.py
  • shm_reader.py как фасад.
• LibreVNA service переведен на backend-подход (librevna_backends.py) с orchestration-оберткой librevna_service.py.

3. Инварианты

• Формат run_config.json сохраняется совместимым с C++ pipeline.
• Форматы snapshot (binary, numpy-directory-v1) сохраняются.
• Сигнатуры ключевых пользовательских входов (gui/main.py, scripts) сохраняются.
• Данные в python_app/data и runtime-файлы в python_app/runtime не реорганизуются автоматически.

4. Основные зависимости

• GUI: PyQt6, pyqtgraph, numpy.
• Hardware: libusb1 через драйвер в hardware_full/librevna_driver.
• Storage/processing tools: numpy, stdlib JSON/Path/mmap/subprocess.

5. Точки расширения

• Новые processing modes: через live-config + GUI section + C++ processor.
• Новые storage backends: реализовать StoreApi.
• Новые hardware adapters: добавить backend/driver и подключить в service/factory.