98 lines
5.0 KiB
Markdown
98 lines
5.0 KiB
Markdown
# 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](./0001-go-module-path.md) - Module path: `git.dcentral.systems/toolz/goplt`
|
|
- [ADR-0002: Go Version](./0002-go-version.md) - Go 1.24.3 (Superseded by ADR-0034)
|
|
- [ADR-0034: Go Version Upgrade to 1.25.3](./0034-go-version-upgrade.md) - Go 1.25.3
|
|
- [ADR-0003: Dependency Injection Framework](./0003-dependency-injection-framework.md) - uber-go/fx
|
|
- [ADR-0004: Configuration Management](./0004-configuration-management.md) - spf13/viper + cobra
|
|
- [ADR-0005: Logging Framework](./0005-logging-framework.md) - go.uber.org/zap
|
|
- [ADR-0006: HTTP Framework](./0006-http-framework.md) - gin-gonic/gin
|
|
- [ADR-0007: Project Directory Structure](./0007-project-directory-structure.md) - Standard Go layout with internal/pkg separation
|
|
- [ADR-0008: Error Handling Strategy](./0008-error-handling-strategy.md) - Wrapped errors with typed errors
|
|
- [ADR-0009: Context Key Types](./0009-context-key-types.md) - Typed context keys
|
|
- [ADR-0010: CI/CD Platform](./0010-ci-cd-platform.md) - GitHub Actions
|
|
- [ADR-0011: Code Generation Tools](./0011-code-generation-tools.md) - go generate workflow
|
|
- [ADR-0012: Logger Interface Design](./0012-logger-interface-design.md) - Logger interface abstraction
|
|
|
|
### Epic 1: Core Kernel & Infrastructure
|
|
|
|
- [ADR-0013: Database ORM Selection](./0013-database-orm.md) - entgo.io/ent
|
|
- [ADR-0014: Health Check Implementation](./0014-health-check-implementation.md) - Custom health check registry
|
|
- [ADR-0015: Error Bus Implementation](./0015-error-bus-implementation.md) - Channel-based error bus with pluggable sinks
|
|
- [ADR-0016: OpenTelemetry Observability Strategy](./0016-opentelemetry-observability.md) - OpenTelemetry for tracing, metrics, logs
|
|
|
|
### Epic 2: Authentication & Authorization
|
|
|
|
- [ADR-0017: JWT Token Strategy](./0017-jwt-token-strategy.md) - Short-lived access tokens + long-lived refresh tokens
|
|
- [ADR-0018: Password Hashing Algorithm](./0018-password-hashing.md) - argon2id
|
|
- [ADR-0019: Permission DSL Format](./0019-permission-dsl-format.md) - String-based format with code generation
|
|
- [ADR-0020: Audit Logging Storage](./0020-audit-logging-storage.md) - PostgreSQL append-only table with JSONB metadata
|
|
|
|
### Epic 3: Module Framework
|
|
|
|
- [ADR-0021: Module Loading Strategy](./0021-module-loading-strategy.md) - Static registration (primary) + dynamic plugin loading (optional)
|
|
|
|
### Epic 5: Infrastructure Adapters
|
|
|
|
- [ADR-0022: Cache Implementation](./0022-cache-implementation.md) - Redis with in-memory fallback
|
|
- [ADR-0023: Event Bus Implementation](./0023-event-bus-implementation.md) - In-process bus (default) + Kafka (production)
|
|
- [ADR-0024: Background Job Scheduler](./0024-job-scheduler.md) - asynq (Redis-backed) + cron
|
|
- [ADR-0025: Multi-tenancy Model](./0025-multitenancy-model.md) - Shared database with tenant_id column (optional)
|
|
|
|
### Epic 6: Observability & Production Readiness
|
|
|
|
- [ADR-0026: Error Reporting Service](./0026-error-reporting-service.md) - Sentry (optional, configurable)
|
|
- [ADR-0027: Rate Limiting Strategy](./0027-rate-limiting-strategy.md) - Multi-level (per-user + per-IP) with Redis
|
|
|
|
### Epic 7: Testing, Documentation & CI/CD
|
|
|
|
- [ADR-0028: Testing Strategy](./0028-testing-strategy.md) - Multi-layered (unit, integration, contract, load)
|
|
|
|
### Architecture & Scaling
|
|
|
|
- [ADR-0029: Microservices Architecture](./0029-microservices-architecture.md) - micromicroservices architecture from day one
|
|
- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md) - Service client abstraction and communication patterns with API Gateway
|
|
- [ADR-0031: Service Repository Structure](./0031-service-repository-structure.md) - Monorepo with service directories
|
|
- [ADR-0032: API Gateway Strategy](./0032-api-gateway-strategy.md) - API Gateway as core infrastructure component
|
|
- [ADR-0033: Service Discovery Implementation](./0033-service-discovery-implementation.md) - Consul-based service discovery (primary), Kubernetes as alternative
|
|
|
|
## Adding New ADRs
|
|
|
|
When making a new architectural decision:
|
|
|
|
1. Create a new file: `XXXX-short-title.md` (next sequential number)
|
|
2. Follow the ADR template
|
|
3. Update this README with the new entry
|
|
4. Set status to "Proposed" initially
|
|
5. Update to "Accepted" after review/approval
|
|
|
|
## References
|
|
|
|
- [ADR Template](https://adr.github.io/madr/)
|
|
- [Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
|
|
|