kwork-api/docs/ARCHITECTURE.md

# Architecture — kwork-api

## 📐 Обзор

**kwork-api** — асинхронный Python клиент для Kwork.ru API с полной типизацией и документацией.

---

## 🏗️ Архитектура

```
┌─────────────────────────────────────────────────────────┐
│                    User Application                      │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                   KworkClient                            │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Authentication Layer                             │  │
│  │  - login() / token auth                           │  │
│  │  - Session management                             │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────┐  │
│  │  API Groups                                       │  │
│  │  - catalog, projects, user, reference, ...       │  │
│  └──────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────┐  │
│  │  HTTP Layer (httpx)                               │  │
│  │  - HTTP/2 support                                 │  │
│  │  - Timeout handling                               │  │
│  │  - Error handling                                 │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              Kwork.ru API (HTTPS)                        │
└─────────────────────────────────────────────────────────┘
```

---

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

```
kwork-api/
├── src/kwork_api/
│   ├── __init__.py          # Public API
│   ├── client.py            # KworkClient + API groups
│   ├── models.py            # Pydantic models
│   └── errors.py            # Exception classes
│
├── tests/
│   ├── test_client.py       # Client tests
│   ├── test_models.py       # Model tests
│   └── test_all_endpoints.py # Endpoint tests
│
├── docs/
│   ├── index.md             # Quick start
│   ├── api-reference.md     # API docs
│   ├── RELEASE.md           # Release guide
│   └── ARCHITECTURE.md      # This file
│
├── .github/workflows/
│   └── ci.yml               # CI/CD pipeline
│
├── pyproject.toml           # Project config
├── uv.lock                  # Dependencies lock
└── README.md                # Main documentation
```

---

## 🔑 Компоненты

### 1. KworkClient

**Ответственность:** Основное взаимодействие с API

**Функции:**
- Аутентификация (login / token)
- Управление сессией
- Делегирование API группам

**API Groups:**
```python
client.catalog      # CatalogAPI
client.projects     # ProjectsAPI
client.user         # UserAPI
client.reference    # ReferenceAPI
client.notifications # NotificationsAPI
client.other        # OtherAPI
```

---

### 2. Models (Pydantic)

**Ответственность:** Валидация и типизация ответов API

**Категории:**
- **User models:** KworkUser, AuthResponse
- **Kwork models:** Kwork, KworkDetails, KworkCategory
- **Project models:** Project, ProjectsResponse
- **Review models:** Review, ReviewsResponse
- **Notification models:** Notification, Dialog
- **Reference models:** City, Country, TimeZone, Feature, Badge
- **Error models:** ErrorDetail, APIErrorResponse

---

### 3. Errors

**Ответственность:** Обработка ошибок API

**Иерархия:**
```
KworkError (base)
├── KworkAuthError      # 401, 403
├── KworkApiError       # 4xx, 5xx
│   ├── KworkNotFoundError    # 404
│   ├── KworkRateLimitError   # 429
│   └── KworkValidationError  # 400
└── KworkNetworkError   # Network issues
```

---

### 4. HTTP Layer (httpx)

**Ответственность:** HTTP запросы

**Функции:**
- HTTP/2 поддержка
- Таймауты
- Cookies management
- Token authentication
- Error handling

---

## 🔄 Flow: Аутентификация

```
User → KworkClient.login(username, password)
                │
                ▼
        POST /signIn (cookies)
                │
                ▼
        POST /getWebAuthToken (token)
                │
                ▼
        Store token + cookies
                │
                ▼
        Return authenticated client
```

---

## 🔄 Flow: API Request

```
User → client.catalog.get_list(page=1)
                │
                ▼
        CatalogAPI.get_list()
                │
                ▼
        KworkClient._request()
                │
                ▼
        httpx.AsyncClient.post()
                │
                ▼
        KworkClient._handle_response()
                │
                ▼
        CatalogResponse.model_validate()
                │
                ▼
        Return typed response
```

---

## 🚀 CI/CD Pipeline

```
Push/Tag → GitHub Actions
    │
    ├── Test Job
    │   ├── Install UV + Python
    │   ├── Run linters (ruff)
    │   ├── Run tests (pytest)
    │   └── Upload coverage
    │
    ├── Build Job
    │   ├── Build wheel + sdist
    │   └── Upload artifacts
    │
    ├── Publish Job (on tag)
    │   ├── Download artifacts
    │   └── Publish to Gitea Registry
    │
    └── Docs Job
        ├── Build MkDocs
        └── Upload site
```

---

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

### Runtime
- `httpx[http2]>=0.26.0` — HTTP client
- `pydantic>=2.0.0` — Data validation
- `structlog>=24.0.0` — Logging

### Development
- `pytest>=8.0.0` — Testing
- `pytest-cov>=4.0.0` — Coverage
- `pytest-asyncio>=0.23.0` — Async tests
- `respx>=0.20.0` — HTTP mocking
- `ruff>=0.3.0` — Linting
- `mkdocs + mkdocstrings` — Documentation

---

## 🔒 Безопасность

- **Токены:** Не сохраняются в логах
- **Пароли:** Передаются только при login()
- **Сессии:** Token + cookies хранятся в клиенте
- **HTTPS:** Все запросы через HTTPS

---

## 📈 Производительность

- **Async/Await:** Неблокирующие запросы
- **HTTP/2:** Multiplexing запросов
- **Connection pooling:** Переиспользование соединений
- **Timeouts:** Защита от зависаний

---

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

- **Unit тесты:** 92% coverage
- **Mock HTTP:** respx для изоляции
- **Async tests:** pytest-asyncio
- **CI:** Автоматический прогон при каждом коммите

---

## 📝 Лицензия

MIT License — свободное использование с указанием авторства.