architect/_archive/2025-11-26-cleanup/system-docs/architecture/1-structural.md

Структурное измерение

Версия: 1.0.0
Дата: 2025-11-19

Что описывает это измерение

Вопрос: Где что находится в системе?

Ответ:
- Иерархия папок
- Обязательные файлы
- Связи между элементами
- Типы структур

НЕ описывает:
- Что делают файлы (функциональное)
- Как выполняются операции (процессное)
- Кто с чем работает (ролевое)

7-уровневая иерархия

Уровень 1: Экосистема

/opt/claude-workspace/

Корень всей системы.

Уровень 2: Подсистемы

/opt/claude-workspace/
├── system/          # Системные компоненты
├── platform/        # Платформа v1
├── platform-v2/     # Платформа v2 (будущее)
├── projects/        # Проекты
├── infra/           # Инфраструктура
├── components/      # Компоненты
├── library/         # Библиотеки
├── templates/       # Шаблоны
└── scripts/         # Скрипты

Уровень 3: Приложения

projects/{name}/
├── design/          # Проектирование
├── management/      # Управление
├── infrastructure/  # Инфра (опц)
└── solution/        # Решение

Уровень 4: Модули

solution/
├── code/            # Код
├── config/          # Конфиги (опц)
└── data/            # Данные (опц)

Уровень 5: Компоненты

code/
├── modules/         # Модули приложения
├── utils/           # Утилиты
├── tests/           # Тесты
└── pages/           # Страницы (для UI)

Уровень 6: Функции

modules/products/
├── crud.py          # CRUD операции
├── queries.py       # Запросы
└── __init__.py      # Инициализация

Уровень 7: Элементы

# crud.py
def create_product()
def read_product()
def update_product()
def delete_product()

Типы папок верхнего уровня

system/ — Системные компоненты

Назначение: Общее для всех платформ и проектов

Структура:

system/
├── docs/                 # Документация системы
│   ├── CONCEPT.md
│   ├── ARCHITECTURE.md
│   ├── architecture/
│   ├── specifications/
│   └── reference/
│
├── orchestrator.ai.md    # Агент-оркестратор
├── claude-code.ai.md     # Агент инструментов
├── terminal.ai.md        # Агент интерфейса
└── integrator.ai.md      # Агент интеграций

platform/ — Платформа v1

Назначение: Стандарты и процедуры v1

Структура:

platform/
├── docs/                 # Документация v1
├── procedures/           # Процедуры
├── templates/            # Шаблоны
├── agents/               # Конфигурации агентов
└── standard.yaml         # Стандарты

projects/ — Проекты

Назначение: Конкретные приложения

Структура:

projects/
├── {name}/              # Проект
│   ├── CLAUDE.md        # ← для AI
│   ├── README.md        # ← для людей
│   ├── index.yaml       # ← навигация
│   ├── design/
│   ├── management/
│   └── solution/

infra/ — Инфраструктура

Назначение: Серверы, облако, сервисы

Структура (ready):

infra/@{name}/
└── config.yaml          # ← метаданные

Структура (project):

infra/{name}/
├── config.yaml          # ← метаданные
├── CLAUDE.md            # ← для Infra-agent
├── design/
└── solution/

components/ — Компоненты

Назначение: Переиспользуемый код

Структура:

components/
├── index.yaml
└── {name}/
    ├── README.md
    ├── component.yaml
    └── src/

library/ — Библиотеки

Назначение: Общий код, утилиты

Структура:

library/
├── index.yaml
└── {name}/
    ├── README.md
    └── src/

templates/ — Шаблоны

Назначение: Шаблоны для создания

Структура:

templates/
├── index.yaml
└── {type}/
    ├── structure.yaml
    └── template/

scripts/ — Скрипты

Назначение: Автоматизация

Структура:

scripts/
├── index.yaml
├── backup/
├── deploy/
└── maintenance/

Типы проектов

APPLICATION

Полная структура:

projects/{name}/
├── CLAUDE.md            ✅ обязательно
├── README.md            ✅ обязательно
├── index.yaml           ✅ обязательно
│
├── design/              ✅ обязательно
│   ├── PROJECT.md       ✅ описание
│   └── spec.md          ⚙️ спецификация
│
├── management/          ✅ обязательно
│   ├── README.md        ⚙️ процедуры
│   └── changelog.md     ⚙️ история
│
├── infrastructure/      ⚙️ опционально
│   ├── deployment.md
│   └── monitoring.md
│
└── solution/            ✅ обязательно
    └── code/            ✅ код приложения

PLATFORM

Структура метаданных:

projects/{name}/
├── CLAUDE.md            ✅ контекст
├── README.md            ✅ описание
├── index.yaml           ✅ индекс
├── LOCATION.md          ✅ где код
└── design/
    └── PROJECT.md       ✅ описание платформы

Код в отдельной папке:

/{platform-name}/        # вне projects/
├── docs/
├── agents/
└── apps/

TEMPLATE

Структура:

templates/{name}/
├── README.md
├── structure.yaml       # описание структуры
├── variables.yaml       # переменные
└── template/            # файлы шаблона

UTILITY

Минимальная структура:

projects/{name}/
├── CLAUDE.md
├── README.md
├── design/
│   └── PROJECT.md
└── solution/
    └── code/            # код утилиты

Типы инфраструктуры

ready — Готовая инфраструктура

Только config.yaml:

infra/@{name}/
└── config.yaml          # usage: ready

С дополнительными файлами:

infra/@{name}/
├── config.yaml          # usage: ready
├── README.md            # описание
└── access.md            # как подключиться

project — Создаваемая инфраструктура

Полная структура:

infra/{name}/
├── config.yaml          # usage: project
├── CLAUDE.md            # для Infra-agent
├── README.md
├── index.yaml
├── design/
│   └── plan.md
└── solution/
    └── terraform/       # или ansible/

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

Матрица

Папка README.md CLAUDE.md index.yaml config.yaml
system/ ✅ ❌ ✅ ❌
platform/ ✅ ❌ ✅ ❌
projects/{name}/ ✅ ✅ ✅ ❌
infra/{name}/ (ready) ⚙️ ❌ ❌ ✅
infra/{name}/ (project) ✅ ✅ ✅ ✅
components/{name}/ ✅ ❌ ❌ ❌
library/{name}/ ✅ ❌ ❌ ❌
templates/{name}/ ✅ ❌ ❌ ❌

Назначение

README.md — для людей
- Что это
- Зачем нужно
- Как использовать

CLAUDE.md — для AI агентов
- Роль агента
- Задачи
- Ограничения

index.yaml — для навигации
- Список файлов
- Назначение
- Метаданные

config.yaml — для инфраструктуры
- Тип и статус
- Доступы
- Спецификации

Связи между элементами

Через index.yaml

# /opt/claude-workspace/index.yaml
projects:
  marketplace:
    path: "projects/marketplace/"
    infra: "@infra-dev-pro"  # ← связь с инфрой

# infra/@infra-dev-pro/config.yaml
projects:
  - name: "marketplace"  # ← обратная связь
    path: "/opt/workspace/projects/marketplace/"

Через LOCATION.md

# projects/platform-v2/LOCATION.md

Основной код: /opt/claude-workspace/platform-v2/

Через символические ссылки

# Версионирование
current: "@latest"  # → v2.0.0
stable: "@stable"   # → v1.5.2

Принципы организации

1. Самодокументирование

Имя папки = назначение:
- design/ — очевидно проектирование
- solution/ — очевидно решение
- management/ — очевидно управление

2. Предсказуемость

Одинаковая структура для всех проектов:

projects/{любой}/
├── CLAUDE.md       ← всегда здесь
├── design/         ← всегда здесь
└── solution/       ← всегда здесь

3. Масштабируемость

Легко добавить новый проект:

mkdir -p projects/new-project/{design,management,solution}

4. Изоляция

Каждый проект в своей папке:

projects/
├── marketplace/    ← изолирован
├── pim-drupal/     ← изолирован
└── platform-v2/          ← изолирован

Следующее измерение

Следующее: 2-functional.md — что делает система

Назад: ../ARCHITECTURE.md — обзор архитектуры