технічний опис архітектури

arch.md

ТЕХНІЧНА ДОКУМЕНТАЦІЯ

Архітектура системи OLX NextGen (Clean Architecture, ASP.NET Core)

Проєкт: OLX NextGen — модернізація платформи OLX.ua Версія: 1.0 Дата: 30 січня 2026 Цільова аудиторія: Backend-розробники, Tech Lead, Solution Architect, DevOps

---

1. Мета документа

Цей документ описує технічну архітектуру backend-рішення OLX NextGen, реалізовану на ASP.NET Core з використанням принципів Clean Architecture.

Цілі:

• забезпечити масштабованість, тестованість і підтримуваність системи;
• мінімізувати зв’язність між бізнес-логікою та інфраструктурою;
• створити єдине архітектурне бачення для команди.

---

2. Архітектурні принципи

2.1. Clean Architecture (Robert C. Martin)

Основні правила:

• бізнес-логіка не залежить від фреймворків;
• залежності спрямовані всередину;
• UI, БД, зовнішні сервіси — змінні деталі.

2.2. Додаткові принципи

• SOLID
• CQRS (де доцільно)
• Domain-Driven Design (DDD-lite)
• Dependency Injection
• API First

---

3. Високорівнева архітектура

3.1. Загальна схема (логічно)

[ Client (Web / PWA) ]
          |
          v
[ API Gateway / Load Balancer ]
          |
          v
[ ASP.NET Core Web API ]
          |
  -----------------------
  | Application Layer   |
  | Domain Layer        |
  -----------------------
          |
[ Infrastructure Layer ]
          |
[ PostgreSQL | Redis | Elasticsearch ]

---

4. Шарова структура рішення

4.1. Domain Layer (Core)

Відповідальність:

• бізнес-правила;
• доменні моделі;
• інваріанти.

Містить:

• Entities (User, Ad, Payment, Subscription);
• Value Objects (Money, Email);
• Domain Events (AdPublishedEvent);
• Interfaces (Repository contracts).

Не містить:

• EF Core;
• HTTP;
• логування;
• зовнішні сервіси.

---

4.2. Application Layer

Відповідальність:

• use cases;
• orchestration бізнес-логіки.

Містить:

• Commands / Queries (CQRS);
• Handlers;
• DTOs;
• Interfaces сервісів;
• Validation (FluentValidation).

Приклад use case:

• CreateAdCommand
• PurchasePremiumFeatureCommand

---

4.3. Infrastructure Layer

Відповідальність:

• реалізація інтерфейсів;
• інтеграції.

Містить:

• EF Core repositories;
• PostgreSQL;
• Redis cache;
• Elasticsearch client;
• платіжні провайдери (LiqPay, Fondy);
• ML Recommendation API client;
• Email / SMS провайдери.

---

4.4. Presentation Layer (API)

Відповідальність:

• HTTP API;
• аутентифікація;
• авторизація;
• версіонування API.

Містить:

• Controllers;
• Middleware;
• Filters;
• Swagger / OpenAPI.

---

5. Структура solution

/OLX.NextGen.sln
 ├── OLX.Domain
 ├── OLX.Application
 ├── OLX.Infrastructure
 ├── OLX.API
 └── OLX.Tests

---

6. Аутентифікація та безпека

• JWT + Refresh Tokens
• OAuth2 (Google / Facebook)
• Role-based access control (RBAC)
• Policy-based authorization
• Захист від OWASP Top 10

---

7. Дані та зберігання

7.1. Основна БД

• PostgreSQL
• EF Core (Code First)
• Міграції

7.2. Кешування

• Redis
• Cache-aside pattern

7.3. Пошук

• Elasticsearch
• Асинхронна індексація

---

8. Інтеграція ML / AI

• Окремий Recommendation Service
• HTTP / gRPC API
• Feature flags
• Fallback без ML

---

9. Продуктивність та масштабування

• Stateless API
• Horizontal scaling
• Kubernetes (HPA)
• Circuit Breaker (Polly)
• Rate limiting

---

10. Логування та моніторинг

• Structured logging (Serilog)
• Distributed tracing (OpenTelemetry)
• Metrics (Prometheus)
• Alerts (Grafana)

---

11. CI/CD та DevOps

• GitHub Actions / Azure DevOps
• Docker
• Kubernetes
• Blue-Green / Canary deployments

---

12. Тестування

• Unit tests (xUnit)
• Integration tests (TestContainers)
• Contract tests
• Load tests (k6)

---

13. Архітектурні ризики

Ризик	Мітігація
Зростання навантаження	Autoscaling
Залежність від ML	Fallback
Платежі	Idempotency

---

14. Майбутній розвиток

• Винесення критичних модулів у мікросервіси
• Event-driven архітектура
• Saga pattern для платежів

---

Документ є базовим архітектурним орієнтиром і оновлюється разом із розвитком системи.