architecture-audit

Architecture Audit

Глубокий разбор архитектуры проекта.

Принципы

1. Architecture is code's structure at the level above modules - смотрим на границы, ответственности, dependency flow
2. Не путай design pattern с архитектурой - паттерны это micro-level, архитектура это macro-level
3. C4 как лингва франка - context, container, component levels достаточны для большинства проектов

Проверки

A1. C4 Reverse-engineering

Из кода восстановить:

Context level:

• Что система делает (по README, по основным entry points)
• Кто использует (по auth/user models, по API endpoints)
• С чем интегрируется (по external HTTP calls, message queues, external imports)

Container level:

• Web app, worker, scheduler, db, queue, cache - искать в Dockerfile, docker-compose, k8s/, infra/
• Если нет deployment manifests - искать в коде (например наличие celery_app.py → worker container)

Component level:

• Внутренние модули каждого container'а
• Их dependencies друг от друга

Создать диаграммы в Mermaid в docs/audit/<TS>/architecture/c4-inferred.md.

A2. ADR Gap Analysis

Список значимых архитектурных решений:

1. Choice of framework (Django vs FastAPI, React vs Vue)
2. Database choice and schema strategy
3. Auth/authz approach (sessions vs JWT, RBAC implementation)
4. API style (REST vs GraphQL vs RPC)
5. Background job approach (Celery vs RQ, queue choice)
6. Caching strategy
7. Frontend state management (Redux vs Zustand vs Context)
8. Error handling and logging strategy
9. Testing strategy (unit/integration/e2e split)
10. Deployment strategy (containers, orchestration)

Для каждого:

• Видно в коде (yes/no)
• Документировано в ADR (yes/no)
• Если yes/no → ADR gap finding

A3. Deep Modules vs Shallow Modules (Ousterhout)

Из "A Philosophy of Software Design":

• Deep module: small interface, large internal complexity (good)
• Shallow module: large interface relative to functionality (bad - cost of using ≈ implementation cost)

Найти shallow modules:

• Файлы с большим количеством exports/public methods но малым LOC внутренних helpers
• "Wrapper" модули которые просто пробрасывают вызовы дальше

A4. Layering Violations

Если в проекте есть архитектурные слои (по naming convention или по папкам):

• Presentation/views/controllers
• Application/services/use_cases
• Domain/models/entities
• Infrastructure/persistence/external

Искать нарушения flow (presentation → application → domain → infrastructure):

• View напрямую делает SQL query (bypass domain)
• Domain знает про HTTP (impure)
• Infrastructure импортирует domain (правильно: depends on, не imports)

В Python: grep imports across packages. В JS/TS: парсить imports в *.ts файлах. В Go: смотреть import blocks.

A5. Cyclic Dependencies

Между модулями/пакетами не должно быть циклов:

• Python: pydeps -p src/ --max-bacon=2 или ручной анализ
• JS/TS: madge --circular src/
• Go: реже встречается из-за compile-time запрета, но пакеты могут косвенно зависеть

A6. God Modules

Модули которые знают слишком много:

• Файл >1000 LOC

• 20 imports

• Implements N concerns одновременно

Это часто комбинируется с code-audit findings, но здесь акцент на architectural impact - это структурная проблема, не code style.

A7. Inconsistent Abstractions

Похожие задачи решаются разными способами:

• Один view использует ORM напрямую, другой через repository pattern
• Часть HTTP errors через exceptions, часть через return values
• Часть domain validation через Pydantic, часть вручную

Этот finding часто требует ручного анализа Claude'ом - не tool'ы.

Severity Application

См. severity rules в audit-architecture.md команды.

Tooling

Tool	Language	Purpose
pydeps	Python	Module dependency graph
radon cc -s	Python	Cyclomatic complexity per function
madge --circular	JS/TS	Cyclic dependencies
dependency-cruiser	JS/TS	Layering rules enforcement
go list -deps	Go	Dependency listing
gocyclo	Go	Cyclomatic complexity

Output

Записать findings в docs/audit/<TS>/architecture/findings.json (формат см. templates/finding.schema.json).

Дополнительные artifacts:

• c4-inferred.md - C4 диаграммы reverse-engineered
• adr-gaps.md - missing ADRs
• dependency-analysis.md - cycles, god modules

Manual review checklist

В standard и deep mode прочитать топ-3 entry points (main, app.py, server.ts) и оценить:

• Чётко видна структура слоёв
• Composition root явно определён
• Dependency injection последователен
• Нет "magic" globals
• Configuration externalized