PLATFORM_ARCHITECTURE.md

type: concept
title: "Архитектура платформы / Platform Architecture"
status: draft
version: 0.1.0
date: 2026-02-17
owner: architect

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

ЧТО ТАКОЕ ПЛАТФОРМА?

Платформа — система для создания систем, которые создают системы.

МЫ + CLAUDE → ПЛАТФОРМА → КОНСТРУКТОРЫ → РЕШЕНИЯ → РЕЗУЛЬТАТ

УРОВНИ ПЛАТФОРМЫ (вертикальная структура)

Классическая модель (OSI-подобная):

┌─────────────────────────────────────────────────┐
│ L0: ФИЛОСОФИЯ (theory)                          │  ← Теория 9 вопросов
│     - Меркаба, вопросы, системы                 │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│ L1: МЕТОДОЛОГИЯ (concept, standards)            │  ← Как думать
│     - Концепция, принципы, стандарты            │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│ L2: ПЛАТФОРМА (system/core)                     │  ← Ядро
│     - Агенты, ядро, протоколы                   │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│ L3: СЕРВИСЫ (system/*)                          │  ← Компоненты
│     - DMS, PM, Monitor, Scheduler               │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│ L4: БИБЛИОТЕКА (library/)                       │  ← Переиспользование
│     - Connectors, Functions, Utils              │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│ L5: КОНСТРУКТОРЫ (constructors/)                │  ← Визуальные инструменты
│     - Генераторы, билдеры                       │
└─────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────┐
│ L6: РЕШЕНИЯ (solutions/, projects/)             │  ← Бизнес-результаты
│     - Готовые решения, проекты                  │
└─────────────────────────────────────────────────┘

ЧТО ТАКОЕ КОМПОНЕНТ?

Компонент — автономный модуль платформы с чётким назначением.

Признаки компонента:

НЕ компонент:

ТИПЫ КОМПОНЕНТОВ (по реализации)

1. AI-компонент

Что: Набор инструкций для Claude
Формат: .md, .ai.md, CLAUDE.md
Исполнение: Claude читает и следует

Примеры:
- architect/theory/ — теория
- architect/standards/ — стандарты
- system/agents/*.ai.md — AI-агенты

component-name/
├── CLAUDE.md           ← Описание и протокол
├── docs/               ← Детальная документация
└── templates/          ← Шаблоны (если нужны)

2. CODE-компонент

Что: Программный код
Формат: .py, .js, .sh
Исполнение: Интерпретатор/компилятор

Примеры:
- library/connectors/ — коннекторы
- library/functions/ — функции
- infra/scripts/ — скрипты

component-name/
├── src/                ← Исходный код
├── tests/              ← Тесты
├── README.md           ← Документация
└── requirements.txt    ← Зависимости (Python)

3. ГИБРИДНЫЙ компонент (AI + CODE)

Что: AI-инструкции + программный код
Формат: CLAUDE.md + src/
Исполнение: Claude управляет кодом

Примеры:
- system/scheduler/ — планировщик
- system/monitor/ — мониторинг
- system/dms/ — DMS (будет создан)

@component-name.type/
├── CLAUDE.md           ← AI-протокол (как использовать)
├── index.yaml          ← Метаданные
├── README.md           ← Документация для людей
├── src/                ← Код
│   ├── main.py
│   └── ...
├── tests/              ← Тесты
└── docs/               ← Детальная документация

КАТЕГОРИИ КОМПОНЕНТОВ (по назначению)

1. ЯДРО (Core) — L2

Назначение: Базовая функциональность платформы

Компоненты:
- system/core/executor — исполнитель задач
- system/core/dispatcher — диспетчер агентов
- system/agents/ — AI-агенты

Критерий: Без этого платформа не работает

2. СЕРВИСЫ (Services) — L3

Назначение: Функциональные компоненты платформы

Компоненты:
- system/scheduler/ — планировщик задач
- system/monitor/ — мониторинг
- system/dms/ — управление документами (⏳ создать)
- system/pm/ — управление проектами (⏳ создать)

Критерий: Обеспечивают конкретную функцию

3. БИБЛИОТЕКА (Library) — L4

Компоненты:
- library/connectors/ — API коннекторы
- library/functions/ — функции
- library/services/ — сервисы (session, etc)
- library/utils/ — утилиты

Критерий: Используется другими компонентами

4. ИНФРАСТРУКТУРА (Infra) — вспомогательный

Компоненты:
- infra/scripts/ — скрипты (backup, cleanup)
- infra/configs/ — конфигурации

5. КОНСТРУКТОРЫ (Constructors) — L5

Назначение: Визуальные инструменты создания

Компоненты:
- constructors/workflow-builder/ — конструктор процессов
- constructors/form-builder/ — конструктор форм

6. РЕШЕНИЯ (Solutions) — L6

Компоненты:
- solutions/robots/ — роботы
- solutions/bots/ — боты
- projects/org/*/ — бизнес-проекты

Критерий: Конечный продукт для пользователя

ИЕРАРХИЯ КОМПОНЕНТОВ (кто от кого зависит)

┌───────────────────────────────────────────────────┐
│ PROJECTS (L6)                                     │
│ └─ использует Solutions, Constructors             │
└───────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────┐
│ SOLUTIONS (L6)                                    │
│ └─ использует Constructors, Services, Library     │
└───────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────┐
│ CONSTRUCTORS (L5)                                 │
│ └─ использует Services, Library                   │
└───────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────┐
│ SERVICES (L3)                                     │
│ ├─ DMS        → использует Library, Core          │
│ ├─ PM         → использует DMS, Library, Core     │
│ ├─ Scheduler  → использует Library, Core          │
│ └─ Monitor    → использует Library, Core          │
└───────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────┐
│ LIBRARY (L4)                                      │
│ └─ переиспользуемый код                           │
└───────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────┐
│ CORE (L2)                                         │
│ └─ базовая функциональность                       │
└───────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────┐
│ METHODOLOGY (L1)                                  │
│ └─ правила и стандарты                            │
└───────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────────────────────────────────────────┐
│ PHILOSOPHY (L0)                                   │
│ └─ теория                                         │
└───────────────────────────────────────────────────┘

Правило зависимостей:
- Компонент может зависеть ТОЛЬКО от компонентов НИЖЕ по уровню
- Запрещено: L3 → L6 (сервис от решения)
- Разрешено: L6 → L3 (решение от сервиса)

ОСНОВНЫЕ VS ОБСЛУЖИВАЮЩИЕ КОМПОНЕНТЫ

Основные (Domain Components)

PM (Project Management)
├─ Назначение: Управление жизненным циклом проектов
├─ Уровень: L3 (Service)
├─ Зависимости: DMS, Library, Core
└─ Используется: Projects, Solutions

DMS (Document Management)
├─ Назначение: Управление иерархией документов
├─ Уровень: L3 (Service)
├─ Зависимости: Library, Core
└─ Используется: PM, Projects

Agents (AI Agents)
├─ Назначение: Исполнение задач через AI
├─ Уровень: L2 (Core)
├─ Зависимости: Library
└─ Используется: PM, Services

Обслуживающие (Infrastructure Components)

Scheduler
├─ Назначение: Планирование задач по расписанию
├─ Уровень: L3 (Service)
├─ Зависимости: Library
└─ Используется: PM, Monitor, любые компоненты

Monitor
├─ Назначение: Мониторинг здоровья системы
├─ Уровень: L3 (Service)
├─ Зависимости: Library
└─ Используется: Все компоненты

Library
├─ Назначение: Переиспользуемый код
├─ Уровень: L4
├─ Зависимости: нет (базовый уровень)
└─ Используется: Все компоненты выше

ЕДИНЫЙ СТАНДАРТ КОМПОНЕНТА

Минимальная структура (AI-компонент):

component-name/
└── CLAUDE.md           ← Обязательно

Стандартная структура (гибридный):

@component-name.type/
├── CLAUDE.md           ← AI-описание (обязательно)
├── index.yaml          ← Метаданные (обязательно)
├── README.md           ← Документация для людей
│
├── src/                ← Код (если есть)
│   ├── main.py
│   ├── __init__.py
│   └── ...
│
├── tests/              ← Тесты (если код)
│   └── test_*.py
│
├── docs/               ← Детальная документация
│   ├── API.md
│   └── EXAMPLES.md
│
├── templates/          ← Шаблоны (если нужны)
│
└── requirements.txt    ← Зависимости (Python)
    или package.json    ← Зависимости (Node.js)

Обязательные файлы:

CLAUDE.md (шаблон)

---
type: {service|agent|library|tool}
title: "{Название компонента}"
version: {X.Y.Z}
level: {L2|L3|L4|L5|L6}
---

# {Название}

**Уровень:** {L2-L6}
**Тип:** {service|agent|library|tool}
**Зависимости:** {список компонентов}

---

## Назначение

{Что делает компонент в 1-2 предложениях}

---

## Как использовать

### Для AI-агента
{Протокол взаимодействия}

### Для программиста
{API, команды}

---

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

- {component-name} — {зачем}

---

## Примеры

{Примеры использования}

index.yaml (шаблон)

id: component-name
type: service  # service|agent|library|tool
level: L3      # L2|L3|L4|L5|L6
version: "1.0.0"

dependencies:
  - component-id: library
    version: ">=1.0.0"

provides:
  - capability: "document-management"
    interface: "python-api"

metadata:
  owner: architect
  created: "2026-02-17"
  status: active  # draft|active|deprecated

ПРИМЕРЫ КОМПОНЕНТОВ

Пример 1: DMS (Document Management System)

system/dms/                     ← L3 Service (гибридный)
├── CLAUDE.md                   ← AI-протокол
├── index.yaml                  ← type: service, level: L3
├── README.md                   ← Документация
│
├── src/
│   ├── create_project.py       ← Создание проекта из шаблонов
│   ├── assemble_document.py    ← Сборка документа из иерархии
│   ├── validate_structure.py   ← Валидация структуры
│   └── sync_templates.py       ← Синхронизация шаблонов
│
├── tests/
│   └── test_dms.py
│
└── docs/
    ├── API.md                  ← API документация
    └── EXAMPLES.md             ← Примеры использования

Зависимости: library/
Используется: PM, Projects

Пример 2: PM (Project Management)

system/pm/                      ← L3 Service (AI-компонент)
├── CLAUDE.md                   ← PM-SYSTEM алгоритм
├── index.yaml                  ← type: service, level: L3
│
├── standards/                  ← Методология
│   ├── LIFECYCLE.md            ← 15 фаз
│   ├── GATES.md                ← Stage Gates
│   └── ROLES.md                ← Роли
│
└── workflows/                  ← Процессы
    └── project-lifecycle.yaml

Зависимости: DMS, library/
Используется: Projects

Пример 3: Scheduler (планировщик)

system/scheduler/               ← L3 Service (гибридный)
├── CLAUDE.md                   ← Описание
├── index.yaml                  ← type: service, level: L3
│
├── run.py                      ← Основной код
├── schedule.yaml               ← Расписание задач
│
└── tasks/                      ← Задачи
    └── *.py

Зависимости: library/
Используется: PM, Monitor, любые компоненты

ТИПЫ КОМПОНЕНТОВ (суффиксы)

.service    — Сервис (scheduler, monitor, dms)
.agent      — AI-агент (projector, dispatcher)
.tool       — Инструмент (cli, scripts)
.lib        — Библиотека (connectors, utils)
.app        — Приложение (web, mobile)
.system     — Системный компонент (core, platform)

Именование:
- Без суффикса: scheduler/, monitor/
- С суффиксом: @projector.agent/, @dms.service/

Когда использовать суффикс:
- Если компонент модульный (@-префикс)
- Если нужно явно указать тип

ТЕКУЩАЯ СТРУКТУРА ПЛАТФОРМЫ (как есть)

/opt/claude-workspace/

├── architect/                  ← L0-L1: Методология
│   ├── theory/                 — L0: Теория
│   ├── concept/                — L1: Концепция
│   ├── standards/              — L1: Стандарты
│   ├── templates/              — Шаблоны (для DMS)
│   └── research/               — Исследования
│
├── system/                     ← L2-L3: Ядро и сервисы
│   ├── core/                   — L2: Ядро (в разработке)
│   ├── agents/                 — L2: AI-агенты
│   │   ├── dispatcher.ai.md
│   │   ├── projector.ai.md
│   │   └── librarian.ai.md
│   │
│   ├── @projector.agent/       — L2: Агент-модуль
│   ├── @architect.agent/       — L2: Агент-модуль
│   │
│   ├── scheduler/              — L3: Сервис
│   ├── monitor/                — L3: Сервис
│   │
│   ├── [создать] dms/          — L3: Сервис (⏳)
│   └── [создать] pm/           — L3: Сервис (⏳)
│
├── library/                    ← L4: Библиотека
│   ├── connectors/             — API коннекторы
│   ├── functions/              — Функции
│   ├── services/               — Сервисы (session, etc)
│   └── utils/                  — Утилиты
│
├── infra/                      ← Инфраструктура
│   └── scripts/                — Скрипты
│
├── constructors/               ← L5: Конструкторы (в разработке)
│
├── solutions/                  ← L6: Решения
│
└── projects/                   ← L6: Проекты
    └── org/
        ├── pirotehnika/
        └── lideravto/

ГДЕ РАЗМЕЩАТЬ PM И DMS?

Предлагаю:

system/pm/                      ← L3 Service (AI-компонент)
└── CLAUDE.md                   — PM-SYSTEM алгоритм

system/dms/                     ← L3 Service (гибридный)
├── CLAUDE.md
└── src/                        — Код DMS

architect/templates/            ← Данные для DMS
├── 0-universal/
├── 1-domain/
├── 2-class/
└── 3-solution/

architect/standards/pm/         ← Методология PM (ссылки)
├── LIFECYCLE.md
├── GATES.md
└── ROLES.md

Логика:
- system/pm/ — исполнительский слой (алгоритм)
- system/dms/ — сервис управления документами
- architect/templates/ — данные (шаблоны)
- architect/standards/pm/ — методология (теория)