Skip to main content

​
High-Level Design (HLD) Review

Review High-Level Design documents against architecture principles, requirements, and quality standards.

​
Command

arckit hld-review "<project ID or HLD path>"

​
Description

Performs comprehensive review of High-Level Design documents to ensure alignment with architecture principles, requirements coverage, and implementation readiness. Provides structured feedback with blocking issues and recommendations.

​
Arguments

  • Project ID or HLD path: Project identifier or path to HLD document (e.g., ‘001’, ‘vendors/acme/hld-v1.md’)

​
When to Use

  • After receiving vendor HLD
  • Before DLD phase begins
  • During design review gates
  • For vendor proposal evaluation
  • Before implementation approval

​
Required Context

  • Architecture Principles (ARC-000-PRIN-*.md) - MANDATORY
  • Requirements (ARC--REQ-.md) - MANDATORY
  • SOW (Statement of Work) - Recommended
  • Risk Register (ARC--RISK-.md) - Recommended
  • Architecture Diagrams (DIAG) - For cross-reference

​
Review Criteria

​
A. Architecture Principles Compliance

For each principle:
  • ✅ Compliant - Design follows principle
  • ⚠️ Violation - Design violates principle
  • ❓ Exception - Approved deviation
Example checks:
  • Cloud-First: Using cloud-native services?
  • API-First: RESTful API strategy?
  • Security by Design: Encryption, authentication?
  • Microservices: Proper service boundaries?

​
B. Requirements Coverage

For each requirement:
  • Verify coverage in HLD
  • Assess design adequacy
  • Trace to components
Example:
  • NFR-P-001 (<2s response): CDN? Caching? Database indexing?
  • NFR-S-001 (PCI-DSS): Security architecture? Token vault?

​
C. Architecture Quality

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)
Resilience:
  • Fault tolerance (circuit breakers, retries)
  • Disaster recovery (RTO/RPO)
  • Multi-region/AZ deployment
  • Data backup strategy
Operational Excellence:
  • Monitoring and observability
  • CI/CD pipeline
  • Blue-green or canary deployment
  • Runbooks and automation

​
D. Architecture Patterns

  • Patterns used correctly?
  • Anti-patterns identified?
  • Data consistency strategy
  • Integration patterns

​
E. Technology Stack

  • Technologies from approved list?
  • Deprecated technologies avoided?
  • License compliance
  • Team expertise
  • Vendor lock-in risks

​
Risk Assessment

HIGH (Blocking):
  • Principle violations
  • Missing NFRs
  • Security gaps
MEDIUM (Should fix):
  • Suboptimal design
  • Performance concerns
  • Technical debt
LOW (Nice to have):
  • Minor improvements
  • Documentation gaps

​
Review Output

​
Executive Summary

Status:
  • ✅ APPROVED
  • ⚠️ APPROVED WITH CONDITIONS
  • ❌ REJECTED
Key findings: Top 3-5 issues Recommendation: Clear action

​
Detailed Findings

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

​
Action Items

BLOCKING (must fix before approval):
  • Critical security gaps
  • Principle violations
  • Missing critical NFRs
Non-blocking (should fix before implementation):
  • Performance optimizations
  • Documentation gaps
Nice-to-have:
  • Future enhancements

​
Output

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

​
Example Review

​
Input

arckit hld-review "Acme Payment Solutions HLD for project 001"

​
Assessment

  • ✅ Cloud-First: Using AWS cloud-native
  • ✅ API-First: RESTful with OpenAPI
  • ❌ Microservices: Single monolith (VIOLATION)
  • ✅ Security: PCI-DSS compliant
  • ⚠️ Resilience: Single region (RISK)

​
Outcome

Status: APPROVED WITH CONDITIONS Blocking Items:
  1. Must add multi-AZ for 99.99% uptime
  2. Consider microservices migration path

​
Review Scores

  • Scalability: 7/10
  • Security: 9/10
  • Resilience: 6/10
  • Overall: 73/100
  • arckit dld-review - Review Detailed Design (after HLD approval)
  • arckit diagram - Generate diagrams from HLD
  • arckit requirements - Source requirements for review

​
Important Notes

  • HLD review is a GATE - implementation cannot start until approved
  • All findings must reference specific principles or requirements
  • Security and compliance violations are typically blocking
  • Document any assumptions or questions for vendor
  • HLD approval is NOT final sign-off (DLD review comes next)

​
Next Steps

After HLD approval:
  1. Vendor addresses blocking items
  2. Re-review if major changes
  3. Proceed to DLD phase
  4. Update traceability matrix
  5. Schedule DLD review

Build docs developers (and LLMs) love

Get started for freeTalk to us