ARCHITECTURE_CURRENT.md describes today, not a desired tomorrow
`ARCHITECTURE_CURRENT.md` should reproduce the factual current-state architecture: subsystems, flows, boundaries, configuration, and dependencies confirmed by code and other sources. It is not a place for desired architecture, a backlog, or promotional system description.
If code and old docs conflict, code is authoritative for actual behavior, but record the discrepancy itself. Do not automatically rewrite `ARCHITECTURE.md`: preserve it as historical documentation and clearly show what needs verification.
Three levels of confidence
Do not mix these levels in one sentence. A document reader should immediately see what is a fact, what was inferred from an indirect signal, and what still needs a manual run or a question to the owner.
| Label | Meaning | Example |
|---|---|---|
| Confirmed fact | there is a direct evidence anchor | PaymentRetryService calls a specific retry client in source code |
| Assumption / inferred | a logical assumption that is not yet confirmed | team ownership inferred from CODEOWNERS or Git history |
| Manual verification | verification outside static reading is needed | timezone precedence or the complete pause/resume flow in a running environment |
Recommended current-state document structure
- for each subsystem, state its boundary, entry points, dependencies, and evidence;
- for each flow, describe input, decisions, side effects, and output;
- mark inferred ownership explicitly as
inferred, not as a confirmed fact; - add a date or revision context when behavior may change.
# ARCHITECTURE_CURRENT.md
## What this document is
## Subsystems
## Critical flows
## Confirmed facts
## Assumptions
## What needs manual verification
## Discrepancies with historical documentationRelated maps do not duplicate one another
CODEBASE_INVENTORY.md answers “where is what”, MODULE_INVENTORY.md answers “which boundaries and responsible areas exist”, CRITICAL_FLOWS.md answers “how does the runtime scenario pass through the system”, and ARCHITECTURE_CURRENT.md answers “how do these parts actually form the system”. RISK_MAP.md adds the decision dimension: what to do with uncertainty and impact.
`BEHAVIOR_INVENTORY.md` looks from the perspective of business flows and observable behavior. It may reference current architecture, but it should not become a list of classes.
Document without inventing facts
- Collect evidence anchors from source, tests, configuration, and logs.
- Record confirmed facts separately from assumptions.
- Move code/docs discrepancies into their own section.
- Formulate manual verification as a concrete scenario or question for the owner.
- Ask a reviewer to check that the current-state description has not been replaced by a desired design.
- Connect the document to the risk map and behavior inventory.
Canonical lesson source · JavaRush
Open JavaRush material