# Архитектура DotsToSurface

Этот документ описывает **логические слои** проекта и соответствие **физических папок**.

## Три слоя

| Слой | Папки | Ответственность |
|------|-------|-----------------|
| **Engine** (C++) | `src/engine/` | Обработка облака точек: preprocess, PCL, реконструкция, метрики, CLI |
| **Backend** (HTTP) | `backend/` | REST API: пресеты, validate, wizard, вызов CLI, отдача статики Vue |
| **Frontend (Web)** | `frontend/web/` | Dashboard в браузере, Pinia, Three.js viewer |
| **Frontend (Desktop)** | `src/desktop/` | Qt Widgets + QML dashboard, OpenGL viewer |

**Важно:** Python и Vue **не выполняют** пайплайн сами. Backend вызывает бинарник `DotsToSurface --cli` через `subprocess` ([`backend/main.py`](backend/main.py)).

## Карта репозитория

```
DotsToSurface/
├── src/
│   ├── main.cpp           # Entry: --cli или Qt GUI
│   ├── engine/            # Engine — C++ пайплайн
│   │   ├── core/
│   │   ├── strategies/
│   │   ├── adapters/
│   │   ├── algorithms/
│   │   ├── cli/
│   │   ├── factories/
│   │   └── tests/
│   └── desktop/           # Frontend (Desktop) — Qt/QML
│       ├── mainwindow.cpp
│       ├── glview.cpp
│       └── qml/
├── backend/               # Backend — FastAPI
├── frontend/
│   └── web/               # Frontend (Web) — Vue 3
├── docker/                # Infra — сборка и runtime-образ
├── presets/               # Shared — JSON-пресеты
└── DotsToSurface.pro
```

Артефакты сборки **не в git**: `build/`, `frontend/web/dist/`, `frontend/web/node_modules/`.

## Потоки данных

### Web (Docker или локально)

```mermaid
flowchart LR
  Browser[Browser Vue3] -->|HTTP /api/*| FastAPI[backend/main.py]
  FastAPI -->|subprocess| CLI[DotsToSurface --cli]
  CLI --> Engine[PipelineExecutor]
  Engine --> JSON[result.json]
  JSON --> FastAPI
  FastAPI --> Browser
```

### Desktop (Qt)

```mermaid
flowchart LR
  QML[Qt QML Dashboard] --> MainWindow[MainWindow C++]
  MainWindow --> Engine[PipelineExecutor in-process]
  Engine --> GLView[OpenGL viewer]
```

## Что работает без C++ бинарника

| Endpoint / функция | Без `DotsToSurface` |
|--------------------|---------------------|
| `GET /api/catalog`, `/api/presets`, `/api/builtin-presets` | Да |
| `POST /api/validate-config`, `/api/wizard` | Да |
| `GET /api/demo` | Да (точки генерирует Python) |
| `POST /api/run` | **Нет** — нужен CLI |

## Сценарии разработки

### Web-версия целиком (рекомендуется)

```bash
cd docker
docker compose up --build
# → http://localhost:8080
```

### Frontend отдельно

```bash
cd frontend/web
npm install
npm run dev
# → http://localhost:5173, /api проксируется на :8080
```

### Engine + Desktop локально

```bash
qmake DotsToSurface.pro 'DEFINES+=PCL_ENABLED'
make -j$(nproc)
./DotsToSurface
```

## Shared и известный техдолг

- **`presets/`** — JSON-шаблоны; читаются Qt и Backend.
- **`pipelineUiCatalog`** — дублирован в Qt и Vue:
  - [`src/desktop/qml/shared/PipelineUiCatalog.js`](src/desktop/qml/shared/PipelineUiCatalog.js)
  - [`frontend/web/src/catalog/pipelineUiCatalog.js`](frontend/web/src/catalog/pipelineUiCatalog.js)

## Указатели по папкам

- [backend/README.md](backend/README.md)
- [frontend/web/README.md](frontend/web/README.md)
- [src/README.md](src/README.md)
- [docker/README.md](docker/README.md)