0x1d
a38a08ca17
Create ADR documenting the decision to use a monorepo structure with service directories for organizing microservices (Option 1). The ADR covers: - Decision to use monorepo with service directories - Rationale for monorepo vs separate repositories - Proposed directory structure with cmd/ and services/ - Implementation strategy across epics - Consequences and mitigations - Migration path if needed in the future This clarifies how services (Auth, Identity, Authz, Audit) should be organized in the codebase while maintaining service independence and microservices architecture principles.
93 lines
4.6 KiB
Markdown
93 lines
4.6 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
|
|
- [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) - Microservices architecture from day one
|
|
- [ADR-0030: Service Communication Strategy](./0030-service-communication-strategy.md) - Service client abstraction and communication patterns
|
|
- [ADR-0031: Service Repository Structure](./0031-service-repository-structure.md) - Monorepo with service directories
|
|
|
|
## 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)
|
|
|