​

High-Level Design Review

​

What is HLD Review?

• Complies with architecture principles
• Meets all requirements (BR, FR, NFR, INT, DR)
• Addresses security and compliance needs
• Scales appropriately
• Is operationally ready

​

Review Scope

​

A. Architecture Principles Compliance

• Check compliance: Does the HLD follow this principle?
• Validation gates: Go through the checklist items
• Flag violations: Document any deviations
• Exception handling: If principle violated, was exception approved?

• Cloud-First: Are they using cloud-native services or legacy on-prem?
• API-First: Is there an API strategy? RESTful? GraphQL?
• Security by Design: Encryption? Authentication? Authorization?
• Microservices: Proper service boundaries? No distributed monoliths?

​

B. Requirements Coverage

• Verify coverage: Is this requirement addressed in the HLD?
• Design adequacy: Is the proposed design sufficient?
• Trace to components: Which components implement this requirement?

• NFR-P-001 (Response time < 2s): Does architecture support this? CDN? Caching? Database indexing?
• NFR-S-001 (PCI-DSS): Is there a clear security architecture? Token vault? Encryption?

​

C. Architecture Quality Assessment

​

Scalability

• Horizontal scaling strategy
• Load balancing approach
• Database scaling (sharding, read replicas)
• Stateless design

​

Performance

• Caching strategy (Redis, CDN)
• Database optimization
• Asynchronous processing
• API response times

​

Security

• Authentication/Authorization (OAuth, JWT, RBAC)
• Data encryption (at rest, in transit)
• Secrets management
• API security (rate limiting, WAF)
• Compliance (PCI-DSS, HIPAA, GDPR, etc.)

​

Resilience

• Fault tolerance (circuit breakers, retries)
• Disaster recovery (RTO/RPO)
• Multi-region/AZ deployment
• Data backup strategy

​

Operational Excellence

• Monitoring and observability (logs, metrics, traces)
• CI/CD pipeline
• Blue-green or canary deployment
• Runbooks and automation

​

D. Architecture Patterns Review

• Are patterns used correctly? (microservices, event-driven, CQRS, etc.)
• Any anti-patterns? (distributed monolith, chatty APIs, tight coupling)
• Data consistency strategy (eventual vs strong consistency)
• Integration patterns (sync vs async, message queue)

​

E. Technology Stack Review

• Are technologies from approved list?
• Any deprecated technologies?
• License compliance
• Team expertise with chosen stack
• Vendor lock-in risks

​

Risk Assessment

• HIGH: Principle violations, missing NFRs, security gaps
• MEDIUM: Suboptimal design, performance concerns, tech debt
• LOW: Minor improvements, documentation gaps

​

Review Report Format

​

Executive Summary

• Overall status: APPROVED / APPROVED WITH CONDITIONS / REJECTED
• Key findings (top 3-5 issues)
• Recommendation

​

Detailed Findings

• Principle compliance (with violations flagged)
• Requirements coverage matrix
• Architecture quality scores
• Risk assessment
• Open questions for vendor

​

Action Items

• BLOCKING issues (must fix before approval)
• Non-blocking improvements (should fix before implementation)
• Nice-to-have enhancements

​

Approval Conditions (if APPROVED WITH CONDITIONS)

• List specific items vendor must address
• Timeline for remediation
• Re-review requirements

​

Example Usage

​

Review Acme Payment Solutions HLD

/arckit.hld-review Review Acme Payment Solutions HLD for payment gateway project

• Read architecture principles
• Read requirements for payment gateway project (001)
• Ask for HLD document location
• Review against all principles:
  • ✅ Cloud-First: Using AWS cloud-native services
  • ✅ API-First: RESTful API with OpenAPI spec
  • ❌ Microservices: Single monolithic service (VIOLATION - should be microservices)
  • ✅ Security: PCI-DSS compliant architecture with token vault
• Check requirements coverage:
  • ✅ NFR-P-001 (Response time): CDN + Redis caching supports < 2s
  • ✅ NFR-S-001 (PCI-DSS): Compliant architecture
  • ⚠️ NFR-R-001 (99.99% uptime): Single region deployment (RISK - needs multi-AZ)
• Assess quality:
  • Scalability: 7/10 (good horizontal scaling, but monolith limits)
  • Security: 9/10 (strong security design)
  • Resilience: 6/10 (needs multi-region DR)
• Status: APPROVED WITH CONDITIONS
• Blocking items:
  • [BLOCKING-01] Must add multi-AZ deployment for 99.99% uptime
  • [BLOCKING-02] Consider microservices migration path to avoid future tech debt

​

Integration with ArcKit Workflow

​

Before HLD Review

/arckit.principles      # Establish architecture standards
/arckit.requirements    # Define requirements
/arckit.wardley         # Create strategic positioning map

​

During HLD Review

/arckit.hld-review Review vendor HLD

1. Read architecture principles
2. Read requirements
3. Ask for HLD document location
4. Perform comprehensive review
5. Generate review report
6. Write to projects/{project-dir}/vendors/{vendor}/ARC-{PROJECT_ID}-HLDR-v1.0.md

​

After HLD Approval

/arckit.diagram container    # Create container diagram
/arckit.dld-review           # Review Detailed Design

​

Best Practices

​

Be Thorough But Constructive

• Help vendor improve, don’t just criticize
• All findings must reference specific principles or requirements
• Security and compliance violations are typically BLOCKING
• Performance and scalability concerns should be addressed early

​

Document Everything

• Document any assumptions or questions for vendor
• HLD approval is NOT final sign-off (DLD review comes next)
• Keep a paper trail for audit purposes

​

Approval Criteria

• All principles complied with
• All requirements covered
• No blocking issues
• Minor issues documented as recommendations

• Most principles complied with
• Critical requirements covered
• Blocking issues identified with remediation plan
• Re-review required after fixes

• Major principle violations
• Critical requirements not met
• Fundamental architectural flaws
• Security or compliance gaps

​

Output File Format

projects/{project-dir}/vendors/{vendor}/ARC-{PROJECT_ID}-HLDR-v1.0.md

​

Common Review Findings

​

Principle Violations

• ❌ Building commodity components (violates Cloud-First)
• ❌ No API specification (violates API-First)
• ❌ Monolithic architecture (violates Microservices principle)
• ❌ Security as afterthought (violates Security by Design)

​

Requirements Gaps

• ❌ Missing performance targets
• ❌ Security requirements not addressed
• ❌ Integration requirements overlooked
• ❌ Data requirements not covered

​

Architecture Quality Issues

• ⚠️ Single point of failure
• ⚠️ No caching strategy
• ⚠️ Tight coupling between services
• ⚠️ No monitoring/observability plan

​

Technology Stack Issues

• ⚠️ Deprecated technologies
• ⚠️ Vendor lock-in risks
• ⚠️ Team skills gap
• ⚠️ License compliance concerns

​

Related Commands

• /arckit.principles - Establish architecture standards
• /arckit.requirements - Define requirements
• /arckit.wardley - Create strategic positioning map
• /arckit.diagram - Generate architecture diagrams
• /arckit.dld-review - Review Detailed Design next
• /arckit.traceability - Verify requirements traceability