ARCHITECTURE.template.md

Проект: {PROJECT_NAME}
Последнее обновление: {ДАТА}

📑 СОДЕРЖАНИЕ

🎯 ОБЗОР {#обзор}

High-Level Architecture

┌─────────────┐
│   Client    │
│  (Browser)  │
└──────┬──────┘
       │ HTTPS
       ▼
┌─────────────┐
│    Nginx    │
│ (Reverse    │
│   Proxy)    │
└──────┬──────┘
       │
       ▼
┌─────────────┐       ┌─────────────┐
│  Backend    │◄──────┤   Redis     │
│   API       │       │   (Cache)   │
└──────┬──────┘       └─────────────┘
       │
       ▼
┌─────────────┐
│ PostgreSQL  │
│   (DB)      │
└─────────────┘

Архитектурный паттерн

Примеры:
- Monolith - всё в одном приложении
- Microservices - разделение на независимые сервисы
- Layered Architecture - слои presentation/business/data
- Event-Driven - асинхронная обработка через очереди

🧩 КОМПОНЕНТЫ {#компоненты}

1. Frontend

Технологии: {ТЕХНОЛОГИИ}
Расположение: {ПУТЬ}

Ответственность:
- Отображение UI
- Валидация форм (клиентская)
- Взаимодействие с Backend API

Ключевые модули:
- {МОДУЛЬ_1} - назначение
- {МОДУЛЬ_2} - назначение

2. Backend API

Технологии: {ТЕХНОЛОГИИ}
Расположение: {ПУТЬ}

Ответственность:
- Бизнес-логика
- Валидация данных (серверная)
- Работа с БД
- Интеграции с внешними API

Endpoints:
- POST /api/auth/login - авторизация
- GET /api/users - список пользователей
- POST /api/orders - создание заказа

3. База данных

СУБД: PostgreSQL 15 / MySQL 8 / {БД}
Расположение: {СЕРВЕР}

Ответственность:
- Хранение данных
- Транзакции
- Constraints & индексы

Основные таблицы:
- users - пользователи
- orders - заказы
- products - товары

4. Cache (Redis)

Технология: Redis 7.0
Назначение:
- Кеширование частых запросов
- Session storage
- Rate limiting counters

Кешируемые данные:
- API ответы (TTL: 10 минут)
- Справочники (TTL: 1 час)
- Session tokens (TTL: 30 минут)

5. Background Jobs (опционально)

Задачи:
- Отправка email
- Генерация отчётов
- Синхронизация с внешними API

🔄 DATA FLOW {#data-flow}

Пример: Создание заказа

1. User → Frontend
   ├─ Заполняет форму заказа
   └─ Нажимает "Создать"

2. Frontend → Backend API
   ├─ POST /api/orders
   ├─ Headers: Authorization: Bearer {token}
   └─ Body: { items: [...], address: "..." }

3. Backend API
   ├─ Валидирует JWT token
   ├─ Валидирует данные (Pydantic)
   ├─ Проверяет остатки товаров
   ├─ Создаёт Order в БД
   ├─ Создаёт OrderItems в БД
   ├─ Уменьшает остатки (Stock)
   └─ Отправляет задачу в очередь (отправить email)

4. Database
   ├─ BEGIN TRANSACTION
   ├─ INSERT INTO orders ...
   ├─ INSERT INTO order_items ...
   ├─ UPDATE stock ...
   └─ COMMIT

5. Background Job
   └─ Отправляет email подтверждения

6. Backend → Frontend
   └─ Response: { order_id: 123, status: "created" }

7. Frontend → User
   └─ Показывает "✅ Заказ #123 создан"

🗄️ БАЗА ДАННЫХ {#база-данных}

ER Diagram

┌─────────────┐       ┌──────────────┐
│    users    │       │    orders    │
├─────────────┤       ├──────────────┤
│ id (PK)     │◄──────┤ user_id (FK) │
│ email       │       │ status       │
│ password    │       │ total_amount │
│ created_at  │       │ created_at   │
└─────────────┘       └──────┬───────┘
                            │
                            │
                      ┌─────▼────────┐
                      │ order_items  │
                      ├──────────────┤
                      │ order_id(FK) │
                      │ product_id   │
                      │ quantity     │
                      │ price        │
                      └──────────────┘

Нормализация

Почему:
- Отсутствие дублирования данных
- Легкость обновления
- Целостность данных

🔌 API DESIGN {#api-design}

REST Principles

Endpoints следуют REST:
- GET /api/orders - получить список
- GET /api/orders/{id} - получить один
- POST /api/orders - создать
- PUT /api/orders/{id} - обновить полностью
- PATCH /api/orders/{id} - обновить частично
- DELETE /api/orders/{id} - удалить

Response Format

{
  "data": { ... },
  "meta": {
    "page": 1,
    "total": 100
  },
  "errors": []
}

Error Handling

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email"
    }
  }
}

📈 МАСШТАБИРОВАНИЕ {#масштабирование}

Горизонтальное (Horizontal Scaling)

Как:
- Добавлять больше серверов Backend
- Load Balancer распределяет нагрузку

Требования:
- Stateless Backend (session в Redis)
- БД на отдельном сервере

Вертикальное (Vertical Scaling)

Как:
- Увеличивать RAM/CPU сервера БД
- Оптимизировать запросы

Database Scaling

Read Replicas:
- Master (write) + N Replicas (read)
- Читать из replica, писать в master

📊 ДИАГРАММЫ {#диаграммы}

Sequence Diagram: Авторизация

User        Frontend       Backend        Database
 │              │              │              │
 ├─ Login ──────►              │              │
 │              ├─ POST /login─►              │
 │              │              ├─ SELECT user─►
 │              │              ◄───────────────┤
 │              │              │              │
 │              │              ├─ Verify pwd  │
 │              │              ├─ Generate JWT│
 │              ◄──────────────┤              │
 ◄──────────────┤              │              │
 │ Show Dashboard              │              │

Component Diagram

┌────────────────────────────────────────┐
│           Frontend (React)             │
└───────────────┬────────────────────────┘
                │ REST API
┌───────────────▼────────────────────────┐
│         Backend (FastAPI)              │
│  ┌──────────┐  ┌──────────┐           │
│  │ Business │  │   API    │           │
│  │  Logic   │  │ Handlers │           │
│  └─────┬────┘  └────┬─────┘           │
│        │            │                  │
│  ┌─────▼────────────▼─────┐           │
│  │    Data Access Layer   │           │
│  └────────────┬───────────┘           │
└───────────────┼────────────────────────┘
                │
        ┌───────▼────────┐
        │   PostgreSQL   │
        └────────────────┘

Последнее обновление: {ДАТА}
Архитектор: {АВТОР}

🏗️ ARCHITECTURE - Архитектура