architect/concept/ARCHITECTURE.md

Архитектура платформы

Версия: 3.0.0
Дата: 2025-12-18
Статус: ACTIVE
Основано на: ../theory/SYSTEM_TYPES.md

Принцип

ПЛАТФОРМА = AI-СЛОЙ + КОД-СЛОЙ + ИНФРА-СЛОЙ

Уровни системы

╔═══════════════════════════════════════════════════════════════════════════════╗
║                              ОПЕРАТОР                                         ║
╚═══════════════════════════════════════════════════════════════════════════════╝
                                      │
                                      ▼
╔═══════════════════════════════════════════════════════════════════════════════╗
║  УРОВЕНЬ 1: AI-СЛОЙ (агенты)                                                  ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║  CLAUDE.md (Терминал)                                                         ║
║       │                                                                       ║
║       ├── Архитектор       (architect.ai.md)   → методология                  ║
║       └── Проектор         (projector.ai.md)   → управление проектами         ║
║                │                                                              ║
║                ├── Кодер       (coder.ai.md)   → пишет код                    ║
║                ├── Инфра       (infra.ai.md)   → серверы                      ║
║                ├── Аналитик    (analyst.ai.md) → данные                       ║
║                └── Интегратор  (integrator.ai.md) → внешние API               ║
║                                                                               ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║  УРОВЕНЬ 2: КОД-СЛОЙ                                                          ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║  СКРИПТЫ (бизнес-задачи)           СЕРВИСЫ (постоянно работают)               ║
║  └── {project}/solution/scripts/   └── {project}/@*.app/                      ║
║                                                                               ║
║  БИБЛИОТЕКИ (общий код)            КОННЕКТОРЫ (внешние системы)               ║
║  └── library/internal/             └── library/connectors/                    ║
║                                                                               ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║  УРОВЕНЬ 3: ИНФРА-СЛОЙ                                                        ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║  СЕРВЕРЫ                           ПЛАТФОРМЕННЫЕ СЕРВИСЫ                      ║
║  └── infra/@*.server/              └── n8n, NocoDB, Gitea, Portainer          ║
║                                                                               ║
║  ХРАНИЛИЩА                                                                    ║
║  └── infra/@*.storage/                                                        ║
║                                                                               ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║  УРОВЕНЬ 4: ВНЕШНИЙ МИР                                                       ║
╠═══════════════════════════════════════════════════════════════════════════════╣
║                                                                               ║
║  ВНЕШНИЕ API: Ozon, Telegram, 1C, СДЭК, банки и др.                           ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

Терминология

Уровень 1: AI-слой

Термин Определение Файл
Агент AI-контекст с ролью и правилами *.ai.md
Терминал Точка входа, роутинг задач CLAUDE.md
Управляющий Агент, координирующий работу (Архитектор, Проектор) system/agents/*.ai.md
Исполнитель Агент, выполняющий конкретную работу system/agents/*.ai.md

Уровень 2: Ресурсы (Платформа)

Термин Определение Где
Connector API Доступ к внешнему API/сервису library/connectors/api/{name}/
Connector Data Доступ к хранилищу данных library/connectors/data/{name}/
Connector Device Работа с физическим устройством library/connectors/device/{name}/
Parser Чтение/запись формата данных library/functions/parsers/{name}/

Уровень 2.5: Код проекта

Термин Определение Где
Config Настройки для платформенного ресурса projects/{name}/config/*.yaml
Client Инициализированный экземпляр ресурса В коде: OzonClient(config)
Integration Бизнес-процесс из нескольких ресурсов projects/{name}/integrations/{name}/
Service Работающее приложение projects/{name}/services/@{name}.{type}/
Script Разовая задача projects/{name}/scripts/*.py

Уровень 3: Инфра-слой

Термин Определение Где
Сервер Физический/виртуальный хост infra/@*.server/
Хранилище Место для данных (S3, диски) infra/@*.storage/
Платформенный сервис Self-hosted софт (n8n, NocoDB) на серверах

Уровень 4: Внешний мир

Термин Определение Примеры
Внешний API Чужие системы, к которым подключаемся Ozon, Telegram, 1C

Принципы

1. Разделение по ответственности

АГЕНТ       — думает, решает, координирует
CONNECTOR   — доступ к внешнему API
DRIVER      — работа с устройством
ADAPTER     — работа с форматом данных
STORE       — доступ к хранилищу
INTEGRATION — бизнес-процесс
SERVICE     — работает постоянно
ИНФРА       — обеспечивает работу всего

2. Зависимости идут вниз

Агент
  ↓ вызывает
Integration / Script
  ↓ использует
Connector + Adapter + Store (через Client)
  ↓ обращается к
Инфра + Внешние API

3. Зеркальная структура

$WORKSPACE (код)              $DATASPACE (данные)
├── projects/pirotehnika/     ├── projects/pirotehnika/
│   ├── config/               │   ├── prices/
│   ├── integrations/         │   ├── images/
│   └── services/             │   └── exports/

4. Коннектор = 1 система

ozon.py      → только Ozon
telegram.py  → только Telegram
nocodb.py    → только NocoDB

НЕ: ozon_telegram.py (это уже скрипт)

5. Скрипт = 1 задача

weekly_report.py     → делает отчёт
fix_prices.py        → исправляет цены
sync_orders.py       → синхронизирует заказы

НЕ: do_everything.py

Агенты

Иерархия

ТЕРМИНАЛ (CLAUDE.md)
    │
    ├── УПРАВЛЯЮЩИЕ
    │   ├── Архитектор  → методология, стандарты
    │   └── Проектор    → управление проектами
    │
    └── ИСПОЛНИТЕЛИ
        ├── Кодер       → пишет код
        ├── Инфра       → управляет серверами
        ├── Аналитик    → работает с данными
        └── Интегратор  → внешние API

Каскад выполнения

ОПЕРАТОР: "Сделай отчёт Ozon"
    │
    ▼
Терминал: роутинг → "бизнес, pirotehnika, аналитика"
    │
    ▼
Проектор: → "задача для Аналитика"
    │
    ▼
Аналитик: → "запускаю скрипт"
    │
    ▼
Скрипт: weekly_report.py
    │
    ├── Коннектор: ozon.py → Ozon API
    ├── Библиотека: excel.py
    └── Сохранение: S3
    │
    ▼
Результат → Оператору

Список агентов

Агент Файл Роль Тип
Терминал CLAUDE.md Интерфейс, роутинг Системный
Архитектор architect.ai.md Методология Управляющий
Проектор projector.ai.md Управление проектами Управляющий
Кодер coder-v1.ai.md, coder-v2.ai.md Написание кода Исполнитель
Инфра infra.ai.md Серверы, деплой Исполнитель
Аналитик analyst.ai.md Данные, отчёты Исполнитель
Интегратор integrator.ai.md Внешние API Исполнитель

Типы компонентов

Тип Описание Именование Пример
BUSINESS Бизнес-контейнер {name}/ pirotehnika/
CODE Сайт, сервис, API @{name}.{type}/ @ozon.api/
DATA Данные, каталоги _{name}/ _shared/
INFRA Серверы, хранилища @{name}.server/ @dev-pro.server/
PLATFORM Методология, агенты {name}/ architect/, system/
CONNECTOR Коннектор к API {name}.py ozon.py
AGENT AI-агент {name}.ai.md coder-v1.ai.md

Подробнее: ../standards/structure/COMPONENTS.md

Структура файлов

$WORKSPACE (код)

$WORKSPACE/
│
├── CLAUDE.md                        ← Терминал (точка входа)
│
├── architect/                       ← МЕТОДОЛОГИЯ
│   ├── theory/                      ← Теория (LOCKED)
│   ├── concept/                     ← Концепция (PLATFORM.md, RESOURCES.md)
│   └── standards/                   ← Стандарты
│
├── system/                          ← РЕСУРСЫ ПЛАТФОРМЫ
│   ├── agents/                      ← AI-агенты
│   │   └── *.ai.md
│   │
│   ├── connectors/                  ← Внешние API
│   │   ├── marketplaces/ozon/
│   │   ├── messengers/telegram/
│   │   └── accounting/1c/
│   │
│   ├── drivers/                     ← Устройства
│   │   └── printers/label/
│   │
│   ├── adapters/                    ← Форматы данных
│   │   ├── spreadsheets/xlsx/
│   │   └── documents/pdf/
│   │
│   └── stores/                      ← Хранилища
│       ├── sql/postgres/
│       └── object/s3/
│
├── projects/                        ← БИЗНЕС-ПРОЕКТЫ
│   ├── pirotehnika/
│   │   ├── CLAUDE.md
│   │   ├── config/                  ← Конфигурации ресурсов
│   │   ├── integrations/            ← Бизнес-процессы
│   │   ├── services/                ← Приложения (@ozon.api/, @pim.service/)
│   │   └── _shared/                 ← Документация к данным
│   │
│   └── lideravto/
│
└── infra/                           ← ИНФРАСТРУКТУРА
    ├── @dev-pro.server/
    └── @backup.service/

$DATASPACE (данные)

$DATASPACE/
│
├── projects/                        ← Данные бизнес-проектов
│   ├── pirotehnika/
│   │   ├── prices/                  ← Прайсы xlsx
│   │   ├── images/                  ← Фото товаров
│   │   ├── products/                ← Данные 1С
│   │   ├── exports/                 ← Выгрузки
│   │   └── _inbox/                  ← Входящие
│   │
│   └── lideravto/
│
└── backup/                          ← Бэкапы
    ├── critical/
    ├── postgres/
    └── restic/

Инфраструктура

Серверы

Сервер IP Назначение
@dev-pro.server 91.218.142.168 Control Plane, Claude Code
@dev-prod-rf.server 45.144.177.147 Production, Docker
@beget-kondurov.server shared Хостинг сайтов

Платформенные сервисы

Сервис Где Назначение
n8n dev-prod-rf Автоматизация
NocoDB dev-prod-rf База данных + UI
Gitea dev-prod-rf Git репозитории
Portainer dev-prod-rf Docker UI
Uptime Kuma dev-prod-rf Мониторинг
MinIO dev-prod-rf S3 хранилище

Хранилища

Хранилище Назначение
@beget-s3.storage Hub (основные данные)
@yandex-disk.storage Бэкапы

Внешние API

Категория Сервисы
Маркетплейсы Ozon, Wildberries, Яндекс.Маркет
Коммуникации Telegram, Email, SMS
Учёт 1C, МойСклад, СБИС
Доставка СДЭК, Почта России
Платежи Банки, эквайринг
Данные DaData

Связанные документы

См. также: PLATFORM.md — концепция платформы

История

Версия: 3.0.0