(wip) docs(optimizer-analyzer): architecture + sequence diagrams

[mkuchenbecker]

Status

(WIP) — draft, ready for review.

Branch is off linkedin/main. The doc describes the Optimizer Analyzer as introduced by PR #533 (mkuchenb/optimizer-3); referenced symbols (@Transactional on analyzeDatabase, TableOperationsHistoryDto::after, CadencePolicy::intervalFor) come online when #533 merges. The doc itself is forward-looking and merges independently.

Summary

Hand-written architecture + sequence documentation for apps/optimizer-analyzer/.

• apps/optimizer-analyzer/docs/architecture.md — narrative
• apps/optimizer-analyzer/docs/diagrams/component.puml + .png
• apps/optimizer-analyzer/docs/diagrams/sequence.puml + .png

PlantUML source is committed so the diagrams are regenerable; rendered PNGs are committed so the markdown displays on GitHub without extra tooling.

Diagrams

Component view: AnalyzerApplication → AnalyzerRunner → (OperationAnalyzer strategy + 3 repos) → MySQL. The contract with the Scheduler is the table_operations table; no direct call.

Sequence view (one operation type, one analyzer pass):

• Per-process startup: lookup analyzer, fan out across databases via statsRepo.findDistinctDatabaseNames().
• Per-database fan-out: @Transactional analyzeDatabase(...).
• Pre-load: 3 reads in order — ops → history → stats — bounded by tables-per-db.
• Per-table evaluation: isEnabled → shouldSchedule (3-branch CadencePolicy.shouldSchedule — active op / no history / has-history with intervalFor cadence) → save PENDING row inside a per-row try/catch+continue.
• INFO aggregate per database; DEBUG per table.

Iteration

Sequence diagram was iterated on visually against the rendered PNG. Two corrections applied:

1. Repo participant order: switched to Ops → Hist → Stats so the 3 pre-load arrows flow left-to-right instead of crossing.
2. CadencePolicy alt: expanded from 2 cases to the correct 3 (active op / no history / has-history-with-cadence-check) — latestHistory.map(readyAfter).orElse(true) is two real paths in the code.

Out of scope

• Scheduler architecture (separate doc / ticket).
• Authn/authz, observability, REST-trigger endpoints — all tracked via dedicated tickets linked in the doc.

🤖 Generated with Claude Code