How to prepare for an architecture or code review

Turn the concern into a review question

“Is our architecture good?” leaves the reviewer guessing about your priorities. Ask a question that can change a decision: can this integration support the next customer requirement, where does a failed payment leave the order, or what must be addressed before a migration? State the system version and the decision deadline.

List the things the review will not cover. A focused discussion cannot establish that every component is secure, every failure has been tested or the whole product is ready to launch. Broader assurance requires a separately agreed scope and evidence.

Assemble a small evidence pack

• A system map: users, services, data stores and external integrations relevant to the question.
• One representative flow: the normal path, the failure path and who handles recovery.
• Constraints: expected workload, response targets, budget, data sensitivity and team capacity; label estimates as estimates.
• Selected evidence: relevant code paths, tests, sanitized errors or diagrams, with dates and versions.
• Decision history: alternatives considered, assumptions and the reason for the current approach.

arc42 separates a system from its external users and neighboring systems, then describes the interfaces between them. That is a useful structure for a review diagram even if you do not use the full documentation template. arc42: context and scope.

For a code review, select the change or path that supports the question. Google's review guidance looks beyond style to design, intended behavior, unnecessary complexity and tests. Include enough surrounding context for those concerns to be evaluated. Google: what to look for in a code review.

An unknown is useful evidence too. If nobody knows the current peak workload or whether a backup can be restored, say so. A reviewer can distinguish a missing measurement from a demonstrated system defect; silently filling the gap with a confident estimate makes that harder.

Agree access and pre-read before sharing

Start an inquiry with a non-confidential description. Do not paste passwords, tokens, customer data or private repository contents into a public contact form. If the engagement needs private material, agree the scope, access method and permitted use first. Prefer the smallest relevant, redacted evidence set and read-only access where appropriate.

Ask what can realistically be read within the engagement. Sending a large repository immediately before a session does not create an agreement for a full audit. Confirm any pre-read, access setup and written deliverable explicitly; do not assume these are included because a meeting is scheduled.

Make findings usable by the team

Ask the reviewer to separate observed facts, likely explanations and unanswered questions. For each material issue, the team needs to understand the affected behavior, the supporting evidence and the next action. Priority should reflect the business consequence and confidence in the finding, not how fashionable a replacement technology is.

• Confirm which system version and evidence the finding refers to.
• Name the person who will investigate, accept or address it.
• Define how the team will check that a change solved the relevant problem.
• Keep unreviewed areas and remaining uncertainty visible in the handoff.

Robles Consulting's Architecture & Code Review is a focused 120-minute session. A larger assessment with agreed evidence and a written deliverable belongs under Architecture Audit. Use the offer details to choose the right scope before requesting availability.