Specvital

English

한국어

English

한국어

Appearance

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 ​

CategoryExamples
Technology StackFramework selection, library adoption, version upgrades
ArchitectureService boundaries, communication patterns, data flow
API DesignEndpoint structure, versioning strategy, error handling
DatabaseSchema design, migration strategy, indexing approach
InfrastructureDeployment platform, scaling strategy, monitoring
Cross-cuttingSecurity, performance optimization, observability

Templates ​

TemplateUse Case
template.mdStandard ADR for most decisions

Naming Convention ​

XX-brief-decision-title.md
  • XX: Two-digit sequential number (01, 02, ...)
  • Lowercase with hyphens
  • Brief and descriptive titles

Technical Areas ​

AreaAffected Repositories
Parsercore
APIweb
Workerworker
Databaseinfra
Infrastructureinfra
Cross-cuttingmultiple

ADR Index ​

Cross-cutting (All Repositories) ​

#TitleAreaDate
01Static Analysis-Based Instant AnalysisCross-cutting2024-12-17
02Competitive Differentiation StrategyCross-cutting2024-12-17
03API and Worker Service SeparationArchitecture2024-12-17
04Queue-Based Asynchronous ProcessingArchitecture2024-12-17
05Polyrepo Repository StrategyArchitecture2024-12-17
06PaaS-First Infrastructure StrategyInfrastructure2024-12-17
07Shared Infrastructure StrategyInfrastructure2024-12-17
08External Repository ID-Based Data IntegrityData Integrity2024-12-22
09GitHub App Integration StrategyAuthentication2024-12-29
10TestStatus Data ContractData Integrity2024-12-29
11Repository Visibility-Based Access ControlSecurity2026-01-03
12Worker-Centric Analysis LifecycleArchitecture2024-12-16
13Billing and Quota ArchitectureBilling2026-01-18
14AI-Based Spec Document Generation PipelineAI/ML2026-01-18
15Parser Version Tracking for Re-analysisData Integrity2026-01-18
16Multi-Queue Priority Routing ArchitectureArchitecture2026-01-19
17Test File Schema NormalizationDatabase2026-01-19
18GitHub API Cache TablesDatabase2025-12-24
19Hierarchical Spec Document SchemaDatabase2026-01-12
20GitHub App Installation SchemaDatabase2026-01-19
21Quota Reservation for Concurrent RequestsBilling2026-02-01
22Scheduler Removal and Railway Cron MigrationInfrastructure2026-02-02
23Railway IaC DeploymentInfrastructure2026-02-02

Core Repository ​

#TitleAreaDate
01Core Library SeparationCore2024-12-17
02Dynamic Test Counting PolicyCore2024-12-22
03Tree-sitter as AST Parsing EngineParser2024-12-23
04Early-Return Framework DetectionParser2024-12-23
05Parser Pooling DisabledParser2024-12-23
06Unified Framework DefinitionParser2024-12-23
07Source Abstraction InterfaceParser2024-12-23
08Shared Parser ModulesParser2024-12-23
09Config Scope ResolutionConfig2024-12-23
10Standard Go Project LayoutProject2024-12-23
11Integration Testing with Golden SnapshotsTesting2024-12-23
12Parallel Scanning with Worker PoolPerf2024-12-23
13NaCl SecretBox EncryptionCrypto2024-12-23
14Indirect Import Alias Detection UnsupportedParser2025-12-29
15C# Preprocessor Block Attribute Detection LimitationParser2026-01-04
16Domain Hints Extraction SystemAI/ML2026-01-18
17Swift Testing Framework SupportParser2026-01-04
18JUnit 4 Framework SeparationParser2025-12-26
19Vitest 4.0+ test.for/it.for API SupportParser2026-01-03
20Java 21+ Implicit Class DetectionParser2026-01-04
21Rust Macro-Based Test DetectionParser2025-12-27

Worker Repository ​

#TitleAreaDate
01Scheduled Re-analysis ArchitectureArchitecture2024-12-18
02Clean Architecture Layer IntroductionArchitecture2024-12-18
03Graceful Shutdown and Context-Based Lifecycle ManagementArchitecture2024-12-18
04OAuth Token Graceful DegradationReliability2024-12-18
05Analyzer-Scheduler Process SeparationArchitecture2024-12-18
06Semaphore-Based Clone Concurrency ControlConcurrency2024-12-18
07Repository Pattern Data Access AbstractionArchitecture2024-12-18
08SpecView Worker Binary SeparationArchitecture2026-01-13
09Phase 1 V1 Quality Enhancement ArchitectureAI/ML2026-02-04
10Per-User Fairness MiddlewareConcurrency2026-02-02
11Data Retention-Based Cleanup ServiceScheduling2026-02-02
12Phase 2 Behavior CacheAI/ML2026-01-24

Web Repository ​

#TitleAreaDate
01Go as Backend LanguageTech Stack2024-12-18
02Next.js 16 + React 19 SelectionTech Stack2025-12-04
03Chi Router SelectionTech Stack2025-01-03
04TanStack Query SelectionTech Stack2025-01-03
05shadcn/ui + Tailwind CSS SelectionTech Stack2025-01-03
06SQLc SelectionTech Stack2025-01-03
07Next.js BFF ArchitectureArchitecture2025-01-03
08Clean Architecture PatternArchitecture2025-01-03
09DI Container PatternArchitecture2025-01-03
10StrictServerInterface ContractAPI2025-01-03
11Feature-Based Module OrganizationArchitecture2025-01-03
12APIHandlers Composition PatternArchitecture2025-01-03
13Domain Error Handling PatternArchitecture2025-01-03
14slog Structured LoggingObservability2025-01-03
15React 19 use() Hook PatternFrontend2025-01-03
16nuqs URL State ManagementFrontend2025-01-03
17next-intl i18n StrategyFrontend2025-01-03
18next-themes Dark ModeFrontend2025-01-03
19CSS Variable Design Token SystemFrontend2025-01-03
20Skeleton Loading PatternFrontend2025-01-03
21Anonymous User Rate LimitingSecurity2026-01-15
22React Compiler AdoptionFrontend2026-01-19
23Window-Level Virtualization PatternFrontend2026-01-19
24Subscription Period Pro-rata CalculationBilling2026-01-16
25OAuth Return URL HandlingSecurity2026-01-16
26Zustand Client State ManagementFrontend2026-01-23
27Commit-Based Analysis BrowsingFrontend2026-02-03
28Dynamic Cost EstimationFrontend2026-02-03

Process ​

  1. Create: Copy template.md → XX-title.md
  2. Write: Fill in all sections with finalized decision
  3. Localize: Create Korean version in kr/adr/
  4. Review: Submit PR for team review
  5. Merge: Add to index after approval

Open-source test coverage insights

Copyright © 2024 Specvital