Architecture Decision Records (ADR)
🇰🇷 한국어 버전
Documentation of architectural decisions made in the Specvital project.
What is an ADR?
An Architecture Decision Record (ADR) captures an important architectural decision made along with its context and consequences. ADRs help maintain decision history across multi-repository microservices.
When to Write an ADR
| Category | Examples |
|---|---|
| Technology Stack | Framework selection, library adoption, version upgrades |
| Architecture | Service boundaries, communication patterns, data flow |
| API Design | Endpoint structure, versioning strategy, error handling |
| Database | Schema design, migration strategy, indexing approach |
| Infrastructure | Deployment platform, scaling strategy, monitoring |
| Cross-cutting | Security, performance optimization, observability |
Templates
| Template | Use Case |
|---|---|
| template.md | Standard ADR for most decisions |
Naming Convention
XX-brief-decision-title.mdXX: Two-digit sequential number (01, 02, ...)- Lowercase with hyphens
- Brief and descriptive titles
Technical Areas
| Area | Affected Repositories |
|---|---|
| Parser | core |
| API | web |
| Worker | collector |
| Database | infra |
| Infrastructure | infra |
| Cross-cutting | multiple |
ADR Index
Cross-cutting (All Repositories)
| # | Title | Area | Date |
|---|---|---|---|
| 01 | Static Analysis-Based Instant Analysis | Cross-cutting | 2024-12-17 |
| 02 | Competitive Differentiation Strategy | Cross-cutting | 2024-12-17 |
| 03 | API and Worker Service Separation | Architecture | 2024-12-17 |
| 04 | Queue-Based Asynchronous Processing | Architecture | 2024-12-17 |
| 05 | Polyrepo Repository Strategy | Architecture | 2024-12-17 |
| 06 | PaaS-First Infrastructure Strategy | Infrastructure | 2024-12-17 |
| 07 | Shared Infrastructure Strategy | Infrastructure | 2024-12-17 |
| 08 | External Repository ID-Based Data Integrity | Data Integrity | 2024-12-22 |
| 09 | GitHub App Integration Strategy | Authentication | 2024-12-29 |
| 10 | TestStatus Data Contract | Data Integrity | 2024-12-29 |
Core Repository
| # | Title | Area | Date |
|---|---|---|---|
| 01 | Core Library Separation | Core | 2024-12-17 |
| 02 | Dynamic Test Counting Policy | Core | 2024-12-22 |
| 03 | Tree-sitter as AST Parsing Engine | Parser | 2024-12-23 |
| 04 | Early-Return Framework Detection | Parser | 2024-12-23 |
| 05 | Parser Pooling Disabled | Parser | 2024-12-23 |
| 06 | Unified Framework Definition | Parser | 2024-12-23 |
| 07 | Source Abstraction Interface | Parser | 2024-12-23 |
| 08 | Shared Parser Modules | Parser | 2024-12-23 |
| 09 | Config Scope Resolution | Config | 2024-12-23 |
| 10 | Standard Go Project Layout | Project | 2024-12-23 |
| 11 | Integration Testing with Golden Snapshots | Testing | 2024-12-23 |
| 12 | Parallel Scanning with Worker Pool | Perf | 2024-12-23 |
| 13 | NaCl SecretBox Encryption | Crypto | 2024-12-23 |
| 14 | Indirect Import Alias Detection Unsupported | Parser | 2025-12-29 |
Collector Repository
| # | Title | Area | Date |
|---|---|---|---|
| 01 | Scheduled Re-collection Architecture | Architecture | 2024-12-18 |
| 02 | Clean Architecture Layer Introduction | Architecture | 2024-12-18 |
| 03 | Graceful Shutdown and Context-Based Lifecycle Management | Architecture | 2024-12-18 |
| 04 | OAuth Token Graceful Degradation | Reliability | 2024-12-18 |
| 05 | Worker-Scheduler Process Separation | Architecture | 2024-12-18 |
| 06 | Semaphore-Based Clone Concurrency Control | Concurrency | 2024-12-18 |
| 07 | Repository Pattern Data Access Abstraction | Architecture | 2024-12-18 |
Web Repository
| # | Title | Area | Date |
|---|---|---|---|
| 01 | Go as Backend Language | Tech Stack | 2024-12-18 |
Process
- Create: Copy template.md →
XX-title.md - Write: Fill in all sections with finalized decision
- Localize: Create Korean version in
kr/adr/ - Review: Submit PR for team review
- Merge: Add to index after approval
Related Repositories
- specvital/core - Parser engine
- specvital/web - Web platform
- specvital/collector - Worker service
- specvital/infra - Infrastructure