Architecture Decision Records (ADRs)
This directory contains Architecture Decision Records (ADRs) for the Go Platform project.
What are ADRs?
ADRs document important architectural decisions made during the project. They help:
- Track why decisions were made
- Understand the context and constraints
- Review decisions when requirements change
- Onboard new team members
ADR Format
Each ADR follows this structure:
- Status: Proposed | Accepted | Rejected | Superseded
- Context: The situation that led to the decision
- Decision: What was decided
- Consequences: Positive and negative impacts
ADR Index
Epic 0: Project Setup & Foundation
- ADR-0001: Go Module Path - Module path:
git.dcentral.systems/toolz/goplt - ADR-0002: Go Version - Go 1.24.3 (Superseded by ADR-0034)
- ADR-0034: Go Version Upgrade to 1.25.3 - Go 1.25.3
- ADR-0003: Dependency Injection Framework - uber-go/fx
- ADR-0004: Configuration Management - spf13/viper + cobra
- ADR-0005: Logging Framework - go.uber.org/zap
- ADR-0006: HTTP Framework - gin-gonic/gin
- ADR-0007: Project Directory Structure - Standard Go layout with internal/pkg separation
- ADR-0008: Error Handling Strategy - Wrapped errors with typed errors
- ADR-0009: Context Key Types - Typed context keys
- ADR-0010: CI/CD Platform - GitHub Actions
- ADR-0011: Code Generation Tools - go generate workflow
- ADR-0012: Logger Interface Design - Logger interface abstraction
Epic 1: Core Kernel & Infrastructure
- ADR-0013: Database ORM Selection - entgo.io/ent
- ADR-0014: Health Check Implementation - Custom health check registry
- ADR-0015: Error Bus Implementation - Channel-based error bus with pluggable sinks
- ADR-0016: OpenTelemetry Observability Strategy - OpenTelemetry for tracing, metrics, logs
Epic 2: Authentication & Authorization
- ADR-0017: JWT Token Strategy - Short-lived access tokens + long-lived refresh tokens
- ADR-0018: Password Hashing Algorithm - argon2id
- ADR-0019: Permission DSL Format - String-based format with code generation
- ADR-0020: Audit Logging Storage - PostgreSQL append-only table with JSONB metadata
Epic 3: Module Framework
- ADR-0021: Module Loading Strategy - Static registration (primary) + dynamic plugin loading (optional)
Epic 5: Infrastructure Adapters
- ADR-0022: Cache Implementation - Redis with in-memory fallback
- ADR-0023: Event Bus Implementation - In-process bus (default) + Kafka (production)
- ADR-0024: Background Job Scheduler - asynq (Redis-backed) + cron
- ADR-0025: Multi-tenancy Model - Shared database with tenant_id column (optional)
Epic 6: Observability & Production Readiness
- ADR-0026: Error Reporting Service - Sentry (optional, configurable)
- ADR-0027: Rate Limiting Strategy - Multi-level (per-user + per-IP) with Redis
Epic 7: Testing, Documentation & CI/CD
- ADR-0028: Testing Strategy - Multi-layered (unit, integration, contract, load)
Architecture & Scaling
- ADR-0029: Microservices Architecture - micromicroservices architecture from day one
- ADR-0030: Service Communication Strategy - Service client abstraction and communication patterns with API Gateway
- ADR-0031: Service Repository Structure - Monorepo with service directories
- ADR-0032: API Gateway Strategy - API Gateway as core infrastructure component
- ADR-0033: Service Discovery Implementation - Consul-based service discovery (primary), Kubernetes as alternative
Adding New ADRs
When making a new architectural decision:
- Create a new file:
XXXX-short-title.md(next sequential number) - Follow the ADR template
- Update this README with the new entry
- Set status to "Proposed" initially
- Update to "Accepted" after review/approval