Версия: 1.0.0
Дата: 2025-11-19
Статус: Active
Этот документ описывает архитектуру платформы — как концепция воплощена в структуре системы.
Связь с концепцией:
Читать CONCEPT.md → понять идеи → читать ARCHITECTURE.md → понять реализацию
Это НЕ:
- ❌ Концепция (см. CONCEPT.md)
- ❌ Детальные спецификации (см. specifications/)
- ❌ Конкретные форматы файлов
- ❌ Примеры реализации
Это:
- ✅ Обзор 8 измерений архитектуры
- ✅ Связи между измерениями
- ✅ Уровни абстракции
- ✅ Архитектурные схемы
/opt/claude-workspace/
│
├── system/ # 🟢 КЛАСТЕР 1: Система (общее для всех)
│ ├── docs/ # Документация системы
│ └── *.ai.md # Системные агенты
│
├── platform/ # 🟡 КЛАСТЕР 2: Platform v1 (текущая)
│ ├── docs/ # Документация v1
│ ├── procedures/ # Процедуры v1
│ └── templates/ # Шаблоны v1
│
├── platform-v2/ # 🔵 КЛАСТЕР 3: Platform v2 (будущая)
│ ├── language/ # Новый язык
│ └── app-builder/ # Система создания приложений
│
└── projects/ # 🟣 КЛАСТЕР 4: Проекты
└── {name}/ # Конкретные проекты
См. детали: architecture/1-structural.md
1. Экосистема /opt/claude-workspace/
2. Подсистемы system/, platform/, projects/, infra/
3. Приложения projects/{name}/
4. Модули solution/code/
5. Компоненты modules/products/
6. Функции crud.py
7. Элементы create_product()
По назначению:
- system/ — системные компоненты
- platform/ — стандарты платформы
- projects/ — приложения
- infra/ — инфраструктура
- components/ — переиспользуемые компоненты
- library/ — библиотеки кода
- templates/ — шаблоны
- scripts/ — служебные скрипты
По типу проекта:
- APPLICATION — приложение с кодом
- PLATFORM — фреймворк/платформа
- TEMPLATE — шаблон
- UTILITY — утилита
По типу инфраструктуры:
- ready — готовая инфраструктура (только подключение)
- project — создаваемая инфраструктура (с IaC кодом)
| Контекст | README.md | CLAUDE.md | index.yaml | config.yaml |
|---|---|---|---|---|
| Для людей | ✅ | ❌ | ⚙️ | ❌ |
| Для AI | ⚙️ | ✅ | ✅ | ⚙️ |
| Для навигации | ❌ | ❌ | ✅ | ❌ |
| Для инфры | ❌ | ❌ | ❌ | ✅ |
См. детали: architecture/2-functional.md
Orchestrator (оркестратор)
├─ Project-agent (агент проекта)
├─ Infra-agent (агент инфры)
├─ Terminal (интерфейс)
├─ Claude Code (инструменты)
└─ Integrator (API)
Роли:
- Orchestrator — управление на верхнем уровне
- Project-agent — работа внутри проекта
- Infra-agent — создание инфраструктуры
- Terminal — интерфейс с оператором
- Claude Code — знание инструментов
- Integrator — внешние API
80% задач — Уровень 1 (1-2K tokens)
- CLAUDE.md + index.yaml
15% задач — Уровень 2 (5-10K tokens)
- + design/spec.md + management/procedures.md
5% задач — Уровень 3 (20-50K tokens)
- + solution/code/* + весь контекст
См. детали: architecture/3-process.md
1. Создание проекта
Определить тип → Собрать инфо → Создать структуру →
→ Создать файлы → Git commit → Обновить индексы
2. Работа над задачей
Загрузить контекст → Понять задачу → Проверить состояние →
→ Выполнить изменения → Проверить → Commit
3. Миграция версий
Инвентаризация → Анализ → Планирование → Staging →
→ Валидация → Миграция → Верификация → Архив
4. Подключение к инфре
Найти инфру → Загрузить config → Проверить usage →
→ Получить доступы → Подключиться
planning → development → testing → staging → production → archived
См. детали: architecture/4-role.md
Оператор (Человек)
- Полномочия: ВСЁ
- Ответственность: Решения, контроль качества
Orchestrator
- Полномочия: Создание проектов, запуск агентов
- Ограничения: НЕ изменяет код напрямую
Project-agent
- Полномочия: Изменение кода проекта
- Ограничения: Только свой проект
Infra-agent
- Полномочия: Создание инфраструктуры
- Ограничения: Только инфра с usage: project
Claude Code Agent
- Полномочия: Консультации по инструментам
- Ограничения: Не принимает решений
Terminal
- Полномочия: Форматирование вывода
- Ограничения: Не выполняет задачи
Integrator
- Полномочия: API запросы
- Ограничения: Не изменяет код
| Действие | Оператор | Orchestrator | Project-agent | Infra-agent |
|---|---|---|---|---|
| Создать проект | ✅ | ✅ | ❌ | ❌ |
| Изменить код | ✅ | ❌ | ✅ (свой) | ❌ |
| Создать инфру | ✅ | ✅ (запуск) | ❌ | ✅ (свою) |
| Читать всё | ✅ | ✅ | ✅ | ✅ |
Оператор → Orchestrator → (Project-agent | Infra-agent) → Результат
См. детали: architecture/5-technical.md
Общее:
- Git — версионирование
- YAML — конфигурации
- Markdown — документация
- Bash — автоматизация
Platform v1:
- Python — основной язык
- Streamlit — UI фреймворк
- SQLAlchemy — работа с БД
- Pytest — тестирование
Platform v2 (будущее):
- PLATFORM-V2 language — новый язык
- App Builder — система создания приложений
Критерии:
- Простота для AI агентов
- Читаемость кода
- Экосистема и библиотеки
- Производительность
Уровни:
- System-level — Git, Bash, общие утилиты
- Platform-level — Python, Node.js
- Project-level — специфичные библиотеки
Управление:
- Shared vendor (экономия 78-85%)
- Components (переиспользование)
- Templates (стандартизация)
См. детали: architecture/6-information.md
YAML — конфигурации
- Читаемость
- Структурированность
- Поддержка комментариев
Markdown — документация
- Читаемость для людей
- Поддержка AI
- Git-friendly
JSON — данные API
- Стандарт для API
- Простой парсинг
SQLite — локальные БД
- Без сервера
- Файловая БД
- SQL запросы
Чтение:
index.yaml (навигация) → Конкретный файл → Обработка
Запись:
Изменение → Валидация → Сохранение → Обновление индексов
Синхронизация:
Локальный workspace ↔ Git ↔ Удалённый сервер
Обязательные поля:
- version — версия документа/данных
- updated — дата обновления
- status — текущий статус
Опциональные:
- description — описание
- tags — теги для поиска
- links — связи с другими элементами
См. детали: architecture/7-temporal.md
Семантическое версионирование:
- MAJOR.MINOR.PATCH
- 1.0.0 → 1.1.0 → 2.0.0
Что версионируется:
- Документы (version в YAML)
- Код (git tags)
- Платформа (Platform v1, v2)
- API (v1/api/, v2/api/)
Проект:
planning (7 дней) → development (30 дней) → testing (7 дней) →
→ staging (3 дня) → production (бесконечно) → archived
Документ:
Draft → Review → Active → Deprecated → Archived
Стратегия:
- Поэтапная (10 стадий)
- С чекпоинтами
- С возможностью отката
- С валидацией на каждом шаге
Обратная совместимость:
- Старая платформа (v1) работает параллельно с новой (v2)
- Миграция постепенная, не обязательная
- Проекты мигрируют по необходимости
Git:
- Commits — изменения кода
- Tags — версии релизов
- Branches — параллельная работа
Архив:
archive/
├── 2025-11-09-marketplace-old/
├── old-projector/
└── ARCHITECTURE_v2_DRAFT.md
См. детали: architecture/8-spatial.md
Локальный workspace:
/opt/claude-workspace/ ← Основная работа
Удалённые серверы:
@infra-dev-pro 91.218.142.168 (Hetzner EU)
@infra-dev-prod-rf [IP] (Hetzner RU)
@remote-beget kondurov.beget.tech (Shared hosting)
Облачные хранилища:
infra-yandex-disk Яндекс.Диск (бэкапы)
s3-nomenclature S3 Beget (данные)
VPS — полный контроль
- Установка любого ПО
- Root доступ
- Настройка окружения
Shared hosting — ограниченный контроль
- Предустановленное ПО
- SSH доступ
- Ограничения провайдера
Cloud storage — хранение данных
- S3-совместимые API
- Бэкапы
- Синхронизация
Локальный → Удалённый:
git push → Webhook → Deploy script → Restart service
Удалённый → Локальный:
git pull (обновление кода)
rclone sync (обновление данных)
Между серверами:
Rsync, SCP, S3 sync
Объект: "marketplace"
projects/marketplace/Все 8 измерений описывают ОДИН объект, но с разных сторон.
Конфликт структуры и функции:
- Функционально: проект нужно разделить на 2 части
- Структурно: должен быть в одной папке
- Решение: Создать подпапки modules/
Конфликт роли и процесса:
- Процессно: нужно изменить platform/
- Ролево: Project-agent не может менять platform/
- Решение: Эскалация к Orchestrator
Конфликт времени и пространства:
- Временно: нужна миграция на v2
- Пространственно: сервер поддерживает только v1
- Решение: Поэтапная миграция через staging
При конфликте измерений:
ВВЕРХ (к абстрактному):
- Автоматическое
- Для понимания контекста
- Уменьшение детализации
ВНИЗ (к конкретному):
- С подтверждением
- Для выполнения изменений
- Увеличение детализации
Уровень 1 — Обзор (index.yaml)
Что есть? Какие файлы? Где что находится?
Уровень 2 — Контекст (CLAUDE.md + README.md)
Зачем это? Как работает? Какие задачи?
Уровень 3 — Детали (весь код)
Как реализовано? Какие алгоритмы? Где баги?
Каждое измерение детально описано в:
- architecture/1-structural.md
- architecture/2-functional.md
- architecture/3-process.md
- architecture/4-role.md
- architecture/5-technical.md
- architecture/6-information.md
- architecture/7-temporal.md
- architecture/8-spatial.md
Технические требования в:
- specifications/file-formats.md
- specifications/naming-rules.md
- specifications/mandatory-files.md
Быстрый доступ к информации:
- reference/glossary.md
- reference/quick-reference.md
Версия: 1.0.0
Дата: 2025-11-19
Статус: Active
Предыдущий: CONCEPT.md
Следующий: architecture/1-structural.md