# Архитектура Cubenet Backend

## 📐 Схема взаимодействия

```
┌─────────────┐
│   Клиент    │
└──────┬──────┘
       │ REST API
       ▼
┌─────────────────────────────────┐
│     API Gateway (8000)          │
│ - REST endpoints                │
│ - Swagger UI (/swagger-ui)      │
└──────────┬──────────────────────┘
           │ gRPC
           ▼
    ┌──────────────────┐
    │  API (8001)      │
    │ - gRPC Client    │
    └────────┬─────────┘
             │ gRPC
             ▼
    ┌──────────────────────────────────────┐
    │  Microservices (13000-14000)         │
    ├──────────────────────────────────────┤
    │ - User Service (13001)               │
    │ - Template Service (13000+)          │
    │ - [Ваши сервисы]                     │
    └──────────────────────────────────────┘
```

## 🔌 Протоколы коммуникации

### REST API (Client ↔ API Gateway)
- **Порт**: 8000
- **Описание**: REST endpoints для клиентов
- **Документация**: Swagger UI на `/swagger-ui/`
- **Endpoints**:
  - `GET /api/health` - проверка здоровья
  - `GET /api/users` - получить список пользователей
  - `POST /api/users` - создать пользователя

### gRPC (API Gateway ↔ API)
- **Порт**: 9000 (зарезервирован)
- **Описание**: Internal communication

### gRPC (API ↔ Microservices)
- **Порты**: 13000-14000
- **Диапазон**: Для каждого микросервиса свой порт
- **Примеры**:
  - User Service: 13001
  - Другие сервисы: 13002-14000

## 📁 Структура каталогов

```
cubenet_backend/
├── api_gateway/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs          # REST endpoints + Swagger
│
├── api/
│   ├── Cargo.toml
│   └── src/
│       └── main.rs          # gRPC клиент + REST
│
├── microservices/
│   ├── user_service/        # gRPC сервис пользователей
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   │
│   └── template_service/    # Шаблон для новых сервисов
│       ├── Cargo.toml
│       └── src/main.rs
│
├── shared_proto/            # Proto определения
│   ├── Cargo.toml
│   ├── build.rs
│   ├── src/lib.rs
│   └── proto/
│       ├── user.proto
│       └── api.proto
│
└── Cargo.toml              # Workspace конфигурация
```

## 🚀 Запуск проекта

### Всё сразу (требует 3 терминала)

**Терминал 1 - User Service (gRPC, порт 13001):**
```bash
cargo run -p user_service
```

**Терминал 2 - API (gRPC клиент, порт 8001):**
```bash
cargo run -p api
```

**Терминал 3 - API Gateway (REST + Swagger, порт 8000):**
```bash
cargo run -p api_gateway
```

## 📚 Swagger Documentation

После запуска API Gateway, откройте браузер:
```
http://localhost:8000/swagger-ui/
```

Здесь вы сможете:
- Просмотреть все доступные endpoints
- Тестировать API requests
- Изучать схему данных

## 🔧 Создание нового микросервиса

### Шаг 1: Скопировать шаблон
```bash
cp -r microservices/template_service microservices/my_service
```

### Шаг 2: Обновить Cargo.toml
```toml
[package]
name = "my_service"
```

### Шаг 3: Добавить в workspace (корневой Cargo.toml)
```toml
[workspace]
members = ["api_gateway", "api", "microservices/user_service", "microservices/my_service"]
```

### Шаг 4: Определить proto файл
```bash
# Добавить my_service.proto в shared_proto/proto/
# Обновить shared_proto/src/lib.rs
```

### Шаг 5: Реализовать сервис
```bash
# Редактировать microservices/my_service/src/main.rs
```

### Шаг 6: Выбрать порт
Используйте порты из диапазона **13000-14000**:
- 13001 - User Service
- 13002-14000 - Ваши сервисы

## 🔐 Порты и выделение

| Компонент | Порт | Протокол | Тип |
|-----------|------|----------|-----|
| API Gateway | 8000 | HTTP/REST | Public |
| API | 8001 | HTTP/REST | Internal |
| User Service | 13001 | gRPC | Internal |
| Микросервисы | 13000-14000 | gRPC | Internal |

## 📦 Зависимости

- **axum** - Веб-фреймворк (REST)
- **tonic** - gRPC framework
- **tokio** - Async runtime
- **serde** - Сериализация
- **utoipa** - OpenAPI/Swagger генератор
- **prost** - Protocol Buffers

## 🧪 Тестирование

### Проверить REST endpoints
```bash
# Health check
curl http://localhost:8000/api/health

# Получить пользователей
curl http://localhost:8000/api/users

# Создать пользователя
curl -X POST http://localhost:8000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}'
```

### Проверить gRPC сервисы
```bash
# Использовать grpcurl или подобные инструменты
grpcurl -plaintext localhost:13001 list
```

## ⚙️ Конфигурация

Основные конфигурационные параметры:
- `api_gateway` адрес: `127.0.0.1:8000`
- `api` адрес: `127.0.0.1:8001`
- `user_service` gRPC: `127.0.0.1:13001`
- `template_service` gRPC: `127.0.0.1:13000` (по умолчанию)

## 🐛 Отладка

Включить подробное логирование:
```bash
RUST_LOG=debug cargo run -p api_gateway
RUST_LOG=trace cargo run -p api
```

## 📝 Лучшие практики

1. **Модульность**: Каждый микросервис в отдельной папке
2. **Proto files**: Все определения в `shared_proto/proto/`
3. **Порты**: 13000-14000 зарезервированы для микросервисов
4. **Логирование**: Используйте `tracing` для логирования
5. **Ошибки**: Пробрасывайте gRPC Status коды вместо паники