architecture-review

Architecture Review

Purpose

Evaluate architectural decisions before implementation.

Prioritize simplicity, maintainability, consistency, and long-term evolution over unnecessary complexity.

Do not implement code unless explicitly requested.

Workflow

1. Understand the objective

Identify:

• business objective;
• functional requirements;
• non-functional requirements;
• constraints;
• expected growth;
• deployment model;
• affected systems.

Clarify assumptions before evaluating solutions.

---

2. Inspect the existing architecture

Understand:

• repository structure;
• module boundaries;
• dependency graph;
• persistence strategy;
• communication patterns;
• deployment architecture;
• existing conventions.

Respect existing architecture unless there is evidence that it should change.

---

3. Identify architectural impact

Determine whether the proposal affects:

• public APIs;
• persistence;
• authentication;
• authorization;
• integrations;
• event flow;
• transactions;
• scalability;
• observability;
• deployment;
• testing.

Document affected areas.

---

4. Evaluate alternatives

For each reasonable option:

• advantages;
• disadvantages;
• implementation complexity;
• migration complexity;
• operational complexity;
• scalability;
• maintainability.

Prefer the simplest solution that satisfies current requirements.

Avoid solving problems that do not yet exist.

---

5. Evaluate technical risks

Review:

• coupling;
• cohesion;
• dependency direction;
• cyclic dependencies;
• hidden complexity;
• transaction boundaries;
• race conditions;
• deployment risks;
• migration risks;
• rollback strategy.

Identify assumptions that could become future problems.

---

6. Evaluate operational concerns

Consider:

• monitoring;
• logging;
• observability;
• configuration;
• environment management;
• scaling strategy;
• recovery strategy;
• failure modes.

Operational simplicity is part of architecture.

---

7. Recommendation

Recommend a single preferred approach.