​

Detailed Design Review

​

What is DLD Review?

• HLD was approved and conditions met
• All technical details are specified
• Implementation can start immediately
• No ambiguity remains
• Test strategy is comprehensive

​

Prerequisites

​

HLD Approval Required

• Check that HLD was approved (DLD cannot proceed without HLD approval)
• Verify all HLD conditions were addressed
• Confirm no new architectural changes were introduced (if yes, needs HLD re-review)

​

Review Scope

​

A. Component Design Review

• Interface definition: APIs, events, messages clearly defined?
• Data structures: Request/response schemas, DTOs documented?
• Business logic: Core algorithms and workflows specified?
• Error handling: Exception handling strategy defined?
• Dependencies: External services, libraries, frameworks listed?

​

B. API Design Review

• API specifications: OpenAPI/Swagger docs provided?
• Endpoint design: RESTful conventions followed? Proper HTTP methods?
• Request validation: Input validation rules specified?
• Response formats: JSON schemas defined? Error responses documented?
• Authentication: Auth flows detailed? Token formats specified?
• Rate limiting: Throttling strategy defined?
• Versioning: API versioning strategy clear?

​

C. Data Model Review

• Database schema: ERD provided? Tables, columns, types defined?
• Relationships: Foreign keys, indexes, constraints documented?
• Data types: Appropriate types for each field?
• Normalization: Proper normalization (or justified denormalization)?
• Migrations: Schema migration strategy defined?
• Partitioning: Sharding or partitioning strategy if needed?
• Archival: Data retention and archival approach?

​

D. Security Implementation Review

• Authentication implementation: OAuth flows, JWT structure, session management?
• Authorization implementation: RBAC/ABAC model, permission matrix?
• Encryption details: Algorithms (AES-256, RSA), key management (KMS)?
• Secrets management: How are secrets stored? (AWS Secrets Manager, Vault)
• Input sanitization: XSS prevention, SQL injection prevention?
• Audit logging: What gets logged? Log retention policy?
• Compliance mapping: How does each control map to compliance requirements?

​

E. Integration Design Review

• Integration patterns: Sync/async? REST/gRPC/message queue?
• Error handling: Retry logic, circuit breakers, timeouts?
• Data transformation: Mapping between systems defined?
• API contracts: Contract testing approach?
• Service discovery: How services find each other?
• Message formats: Event schemas, message structures?

​

F. Performance Design Review

• Caching strategy: What gets cached? TTL? Invalidation strategy?
• Database optimization: Indexes defined? Query optimization?
• Connection pooling: Pool sizes, timeout configs?
• Async processing: Background jobs, queue workers?
• Batch processing: Batch sizes, scheduling?
• Load testing plan: Performance test scenarios defined?

​

G. Operational Design Review

• Monitoring: Metrics to track? Dashboards defined? Alert thresholds?
• Logging: Log levels, structured logging, log aggregation?
• Tracing: Distributed tracing implementation (Jaeger, X-Ray)?
• Health checks: Liveness/readiness probes defined?
• Configuration: Config management approach (ConfigMaps, Parameter Store)?
• Deployment: CI/CD pipeline defined? Deployment strategy (blue-green, canary)?

​

H. Testing Strategy Review

• Unit testing: Coverage targets? Testing frameworks?
• Integration testing: Test scenarios defined?
• Contract testing: API contract tests specified?
• Performance testing: Load/stress test plans?
• Security testing: SAST/DAST tools? Penetration testing plan?
• UAT approach: User acceptance test criteria?

​

Implementation Readiness Check

• ✅ Can developers start coding immediately with this DLD?
• ✅ Are all technical ambiguities resolved?
• ✅ Are all third-party dependencies identified?
• ✅ Is the test strategy comprehensive?
• ✅ Are deployment procedures clear?

​

Review Report Format

​

Executive Summary

• Status: APPROVED / APPROVED WITH CONDITIONS / REJECTED / NEEDS HLD RE-REVIEW
• Implementation readiness score (0-100)
• Top risks or gaps

​

Detailed Findings

• Component design assessment
• API design review
• Data model evaluation
• Security implementation review
• Integration review
• Performance considerations
• Operational readiness
• Testing strategy assessment

​

Action Items

• BLOCKING issues (must fix before implementation)
• Non-blocking improvements (fix during implementation)
• Technical debt to track

​

Implementation Guidance

• Development sequence recommendations
• Critical path items
• Risk mitigation during implementation

​

Example Usage

​

Review Acme Payment Solutions DLD

/arckit.dld-review Review Acme Payment Solutions DLD for payment gateway

• Check HLD was approved and conditions met
• Ask for DLD document
• Review component design:
  • ✅ Payment Service: Well-defined API, clear business logic
  • ❌ Fraud Service: Missing ML model specification (BLOCKING)
  • ✅ Notification Service: Complete event-driven design
• Review API design:
  • ✅ OpenAPI 3.0 spec provided
  • ✅ Proper REST conventions
  • ⚠️ Missing rate limiting implementation details
• Review data model:
  • ✅ Complete ERD with all relationships
  • ✅ Indexes on high-traffic queries
  • ❌ Missing data retention/archival strategy (BLOCKING)
• Review security:
  • ✅ OAuth 2.0 + JWT implementation detailed
  • ✅ AES-256 encryption with AWS KMS
  • ✅ PCI-DSS controls mapped to code
• Review testing:
  • ✅ 80% unit test coverage target
  • ✅ Integration test scenarios defined
  • ⚠️ Performance test plan incomplete
• Status: APPROVED WITH CONDITIONS
• Blocking items:
  • [BLOCKING-01] Specify fraud detection ML model (algorithm, features, thresholds)
  • [BLOCKING-02] Define data retention policy (7 years for PCI compliance)

​

Integration with ArcKit Workflow

​

Before DLD Review

/arckit.hld-review           # HLD must be approved first
/arckit.diagram component    # Component diagrams help review
/arckit.diagram sequence     # Sequence diagrams show flows

​

During DLD Review

/arckit.dld-review Review vendor DLD

1. Verify HLD approval
2. Read requirements
3. Ask for DLD document location
4. Perform detailed technical review
5. Generate review report
6. Write to projects/{project-dir}/vendors/{vendor}/ARC-{PROJECT_ID}-DLDR-v1.0.md

​

After DLD Approval

/arckit.backlog              # Generate sprint backlog
/arckit.traceability         # Verify complete traceability

​

Best Practices

​

This is the Last Gate

• DLD review is the FINAL gate before implementation
• Any architectural changes require HLD re-review
• DLD must be detailed enough for ANY developer to implement
• All technical decisions must be documented and justified
• Security and compliance details are critical
• Test strategy must be comprehensive

​

Document Everything

• DLD approval means “ready to code” - no ambiguity allowed
• This is the last chance to catch design issues before expensive code changes
• Keep a paper trail for audit purposes

​

Approval Criteria

• HLD conditions met
• All components fully specified
• APIs completely documented (OpenAPI)
• Database schemas complete
• Security implementation detailed
• Test strategy comprehensive
• No blocking issues

• HLD conditions met
• Most components specified
• Blocking issues identified with remediation plan
• Re-review required after fixes

• Critical components missing
• APIs incomplete
• Security gaps
• Test strategy inadequate

• Architectural changes introduced
• Deviations from approved HLD
• New components or patterns

​

Output File Format

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

​

Common Review Findings

​

Component Design Issues

• ❌ Missing API specifications
• ❌ Incomplete data structures
• ❌ No error handling strategy
• ❌ Dependencies not listed

​

API Design Issues

• ❌ No OpenAPI documentation
• ❌ RESTful conventions violated
• ❌ Missing request validation
• ❌ Error responses not documented

​

Data Model Issues

• ❌ No ERD provided
• ❌ Missing indexes
• ❌ Poor normalization
• ❌ No migration strategy

​

Security Implementation Issues

• ❌ Authentication flows unclear
• ❌ Authorization not specified
• ❌ Encryption algorithms missing
• ❌ Secrets management undefined

​

Testing Strategy Issues

• ❌ No coverage targets
• ❌ Integration tests missing
• ❌ Performance tests undefined
• ❌ Security testing not planned

​

Related Commands

• /arckit.hld-review - HLD must be approved first
• /arckit.requirements - Verify requirements coverage
• /arckit.data-model - Reference data model
• /arckit.diagram - Component and sequence diagrams
• /arckit.backlog - Generate sprint backlog after approval
• /arckit.traceability - Verify implementation traceability