arcodange/dance-lessons-coach
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

📝 docs(restructure): split AGENTS.md (1296 → 130 lines) + 9 focused guides #17

Open
arcodange wants to merge 7 commits from feature/restructure-agents-md into main
pull from: feature/restructure-agents-md
merge into: arcodange:main
Conversation 0 Commits 7 Files Changed 24 +83 -128
12 changed files with 83 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Showing only changes of commit 73a3af1552 - Show all commits

2
adr/0008-bdd-testing.md
View File

@@ -4,6 +4,8 @@
* Deciders: Gabriel Radureau, AI Agent * Deciders: Gabriel Radureau, AI Agent
* Date: 2026-04-05 * Date: 2026-04-05
> **⚠️ Structure superseded by ADR-0024.** The framework decision (Godog, in-process test server) remains valid. However, the flat `features/` layout and single `steps.go` file described here were replaced by a modular per-domain structure. See ADR-0024 for the current organisation: `features/{auth,greet,health,jwt,config}/` with domain-specific step files and per-domain `*_test.go` runners. The `cd features && godog` execution pattern is also outdated — each domain now uses `go test`.
## Context and Problem Statement ## Context and Problem Statement
We needed to add behavioral testing to dance-lessons-coach that provides: We needed to add behavioral testing to dance-lessons-coach that provides:

9
adr/0009-hybrid-testing-approach.md
View File

@@ -1,10 +1,11 @@
# Combine BDD and Swagger-based testing # BDD Testing with OpenAPI Documentation
* Status: ✅ Partially Implemented (BDD + Documentation only) * Status: Accepted
* Deciders: Gabriel Radureau, AI Agent * Deciders: Gabriel Radureau, AI Agent
* Date: 2026-04-05 * Date: 2026-04-05
* Last Updated: 2026-04-05 * Last Updated: 2026-04-12
* Implementation Status: BDD testing and OpenAPI documentation completed, SDK generation deferred
> **⚠️ Title corrected.** This ADR was originally named "Combine BDD and Swagger-based testing" with the intent of eventually adding SDK-generated BDD tests as a second layer ("hybrid"). That second layer was deferred and has no concrete plan. The actual architecture is **BDD direct-HTTP testing + OpenAPI documentation via swaggo** — calling it "hybrid" is misleading. SDK generation remains a possible future enhancement but is not tracked by any open issue.
## Context and Problem Statement ## Context and Problem Statement

62
adr/0013-openapi-swagger-toolchain.md
View File

@@ -378,68 +378,6 @@ Added to `.gitea/workflows/go-ci-cd.yaml` lint-format job:
# Format swagger comments manually # Format swagger comments manually
swag fmt swag fmt
# Format is automatically run in:
# - pre-commit hook
# - CI/CD lint-format job
```
=======
### Final Implementation
```bash
# 1. Install swaggo
go install github.com/swaggo/swag/cmd/swag@latest
# 2. Add swagger metadata to main.go
// @title dance-lessons-coach API
// @version 1.0
// @description API for dance-lessons-coach service
// @host localhost:8080
// @BasePath /api
package main
```
### Swag Formatting Integration
To ensure consistent swagger comment formatting, we've integrated `swag fmt` into our workflow:
#### Git Hooks
Added to `.git/hooks/pre-commit`:
```bash
# Run swag fmt to format swagger comments
echo "Running swag fmt..."
if command -v swag >/dev/null 2>&1; then
swag fmt
if [ $? -ne 0 ]; then
echo "ERROR: swag fmt failed"
exit 1
fi
else
echo "swag not installed, skipping swag fmt"
fi
```
#### CI/CD Integration
Added to `.gitea/workflows/go-ci-cd.yaml` lint-format job:
```yaml
- name: Install swag
run: go install github.com/swaggo/swag/cmd/swag@latest
- name: Run swag fmt
run: swag fmt
```
#### Benefits
- **Consistent Formatting**: Automatic formatting of swagger comments
- **Pre-Commit Validation**: Catches issues before commit
- **CI/CD Enforcement**: Ensures formatting in all pull requests
- **Team Consistency**: Everyone follows the same rules
- **Automatic Fixes**: Issues are fixed automatically
#### Usage
```bash
# Format swagger comments manually
swag fmt
# Format is automatically run in: # Format is automatically run in:
# - pre-commit hook # - pre-commit hook
# - CI/CD lint-format job # - CI/CD lint-format job

6
adr/0015-cli-subcommands-cobra.md
View File

@@ -222,7 +222,7 @@ dance-lessons-coach config validate
--- ---
**Status:** Proposed **Status:** Accepted
**Next Review:** 2026-04-12 **Implementation Date:** 2026-04-05
**Implementation Owner:** Arcodange Team **Implementation Owner:** Arcodange Team
**Approvers Needed:** @gabrielradureau **Approved by:** @gabrielradureau

3
adr/0018-user-management-auth-system.md
View File

@@ -1,7 +1,8 @@
# 18. User Management and Authentication System # 18. User Management and Authentication System
**Date:** 2024-04-06 **Date:** 2024-04-06
**Status:** Proposed **Status:** Accepted
**Implementation Date:** 2026-04-08
**Authors:** Product Owner **Authors:** Product Owner
**Decision Drivers:** Security, User Personalization, Admin Functionality **Decision Drivers:** Security, User Personalization, Admin Functionality

5
adr/0019-postgresql-integration.md
View File

@@ -1,10 +1,13 @@
# 19. PostgreSQL Database Integration # 19. PostgreSQL Database Integration
**Date:** 2024-04-07 **Date:** 2024-04-07
**Status:** Proposed **Status:** Accepted (Partial)
**Implementation Date:** 2026-04-08
**Authors:** Product Owner **Authors:** Product Owner
**Decision Drivers:** Data Persistence, Scalability, Production Readiness **Decision Drivers:** Data Persistence, Scalability, Production Readiness
> **⚠️ Pending cleanup:** `pkg/user/sqlite_repository.go` and `gorm.io/driver/sqlite` still present in the codebase. The ADR requires their removal, but no Gitea issue tracks this yet. The PostgreSQL implementation (`pkg/user/postgres_repository.go`) is complete and in use.
## Context ## Context
The dance-lessons-coach application currently uses SQLite with GORM for the user management system (ADR 0018), but since there are no existing users or production data, we can implement PostgreSQL directly as our primary database without migration concerns. The dance-lessons-coach application currently uses SQLite with GORM for the user management system (ADR 0018), but since there are no existing users or production data, we can implement PostgreSQL directly as our primary database without migration concerns.

8
adr/0021-jwt-secret-retention-policy.md
View File

@@ -1,11 +1,13 @@
# 10. JWT Secret Retention Policy # 21. JWT Secret Retention Policy
## Status ## Status
**Proposed** 🟡 **Proposed** 🟡
> **Note:** Basic JWT multi-secret support and graceful rotation are implemented in `pkg/jwt/jwt_secret_manager.go`. The retention cleanup policy (background job, configurable TTL factor) proposed in this ADR is **not yet implemented**.
## Context ## Context
The dance-lessons-coach application requires a robust JWT secret management system that balances security and user experience. As implemented in [ADR-0009](0009-hybrid-testing-approach.md), the system supports multiple JWT secrets for graceful rotation. However, the current implementation lacks a clear policy for secret retention and cleanup. The dance-lessons-coach application requires a robust JWT secret management system that balances security and user experience. The system supports multiple JWT secrets for graceful rotation. However, the current implementation lacks a clear policy for secret retention and cleanup.
### Current State ### Current State
@@ -386,8 +388,8 @@ func maskSecret(secret string) string {
## References ## References
- [ADR-0009: Hybrid Testing Approach](0009-hybrid-testing-approach.md)
- [ADR-0008: BDD Testing](0008-bdd-testing.md) - [ADR-0008: BDD Testing](0008-bdd-testing.md)
- [ADR-0018: User Management and Auth System](0018-user-management-auth-system.md)
- [RFC 7519: JSON Web Tokens](https://tools.ietf.org/html/rfc7519) - [RFC 7519: JSON Web Tokens](https://tools.ietf.org/html/rfc7519)
- [OWASP Key Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html) - [OWASP Key Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html)

54
adr/0022-rate-limiting-cache-strategy.md
View File

@@ -3,6 +3,8 @@
## Status ## Status
**Proposed** 🟡 **Proposed** 🟡
> **⚠️ Not yet implemented.** Gitea issue #13 ("feat: Implement Rate Limiting and Caching Strategy") is open and tracks this work. `go-cache`, `redis`, and `ulule/limiter` are absent from `go.mod`. The phase checkboxes below are corrected to reflect actual status.
## Context ## Context
As the dance-lessons-coach application grows and potentially serves multiple users simultaneously, we need to implement rate limiting to: As the dance-lessons-coach application grows and potentially serves multiple users simultaneously, we need to implement rate limiting to:
@@ -284,38 +286,38 @@ func GetCacheKey(prefix, entityType, entityID string) string {
## Implementation Phases ## Implementation Phases
### Phase 1: In-Memory Cache (Current Sprint) ### Phase 1: In-Memory Cache (Current Sprint)
- ✅ Research and select in-memory cache library - ❌ Research and select in-memory cache library
- ✅ Implement cache interface and in-memory service - ❌ Implement cache interface and in-memory service
- ✅ Add cache configuration to config package - ❌ Add cache configuration to config package
- ✅ Implement basic cache operations (set, get, delete) - ❌ Implement basic cache operations (set, get, delete)
- ✅ Add TTL support and automatic cleanup - ❌ Add TTL support and automatic cleanup
- ✅ Cache JWT validation results - ❌ Cache JWT validation results
- ✅ Add cache metrics and monitoring - ❌ Add cache metrics and monitoring
### Phase 2: Redis-Compatible Cache (Next Sprint) ### Phase 2: Redis-Compatible Cache (Next Sprint)
- ✅ Set up Dragonfly/KeyDB in development environment - ❌ Set up Dragonfly/KeyDB in development environment
- ✅ Implement Redis cache service - ❌ Implement Redis cache service
- ✅ Add configuration for Redis connection - ❌ Add configuration for Redis connection
- ✅ Implement cache fallback strategy (Redis → in-memory) - ❌ Implement cache fallback strategy (Redis → in-memory)
- ✅ Add health checks for Redis connection - ❌ Add health checks for Redis connection
- ✅ Implement distributed cache invalidation - ❌ Implement distributed cache invalidation
### Phase 3: Rate Limiting (Following Sprint) ### Phase 3: Rate Limiting (Following Sprint)
- ✅ Research and select rate limiting library - ❌ Research and select rate limiting library
- ✅ Implement rate limiter service - ❌ Implement rate limiter service
- ✅ Add rate limit configuration - ❌ Add rate limit configuration
- ✅ Implement Chi middleware for rate limiting - ❌ Implement Chi middleware for rate limiting
- ✅ Add rate limit headers to responses - ❌ Add rate limit headers to responses
- ✅ Implement IP whitelisting - ❌ Implement IP whitelisting
- ✅ Add endpoint-specific rate limits - ❌ Add endpoint-specific rate limits
### Phase 4: Advanced Features (Future) ### Phase 4: Advanced Features (Future)
- ✅ Cache warming for critical data - ❌ Cache warming for critical data
- ✅ Two-level caching (Redis + in-memory) - ❌ Two-level caching (Redis + in-memory)
- ✅ Cache compression for large objects - ❌ Cache compression for large objects
- ✅ Rate limit exemptions for admin users - ❌ Rate limit exemptions for admin users
- ✅ Dynamic rate limit adjustment - ❌ Dynamic rate limit adjustment
- ✅ Cache analytics and usage patterns - ❌ Cache analytics and usage patterns
## Configuration ## Configuration

2
adr/0023-config-hot-reloading.md
View File

@@ -4,6 +4,8 @@
* Deciders: Gabriel Radureau, AI Agent * Deciders: Gabriel Radureau, AI Agent
* Date: 2026-04-05 * Date: 2026-04-05
> **⚠️ Not yet implemented.** No `ConfigManager` exists in `pkg/config/` and Viper's `WatchConfig()` is not wired up. However, `features/config/config_hot_reloading.feature` has been written — BDD scenarios exist for a feature that is not yet built. Those tests are expected to fail until implementation begins.
## Context and Problem Statement ## Context and Problem Statement
The dance-lessons-coach application currently loads configuration once at startup using Viper, which supports file-based configuration, environment variables, and defaults. However, the current implementation does not support runtime configuration changes without restarting the application. The dance-lessons-coach application currently loads configuration once at startup using Viper, which supports file-based configuration, environment variables, and defaults. However, the current implementation does not support runtime configuration changes without restarting the application.

2
adr/0024-bdd-test-organization-and-isolation.md
View File

@@ -1,7 +1,7 @@
# ADR 0024: BDD Test Organization and Isolation Strategy # ADR 0024: BDD Test Organization and Isolation Strategy
## Status ## Status
**Proposed** 🟡 **Accepted** ✅
## Context ## Context

5
adr/0025-bdd-scenario-isolation-strategies.md
View File

@@ -1,7 +1,10 @@
# ADR 0025: BDD Scenario Isolation Strategies # ADR 0025: BDD Scenario Isolation Strategies
## Status ## Status
**Proposed** 🟡 **Accepted (Partial)** 🟡
Phase 1 (schema-per-scenario DB isolation + `ScenarioState` manager in `pkg/bdd/steps/scenario_state.go`) is implemented.
Phase 2 (cache key prefix strategy, in-memory store `Reset()` methods) is pending — blocked on ADR-0022 (rate limiting/cache) not yet implemented.
## Context ## Context

53
adr/README.md
View File

@@ -13,24 +13,24 @@ This directory contains Architecture Decision Records (ADRs) for the dance-lesso
| 0005 | Graceful Shutdown | ✅ Accepted | | 0005 | Graceful Shutdown | ✅ Accepted |
| 0006 | Configuration Management | ✅ Accepted | | 0006 | Configuration Management | ✅ Accepted |
| 0007 | OpenTelemetry Integration | ✅ Accepted | | 0007 | OpenTelemetry Integration | ✅ Accepted |
| 0008 | BDD Testing | ✅ Accepted | | 0008 | BDD Testing with Godog | ✅ Accepted (structure superseded by 0024) |
| 0009 | Hybrid Testing Approach | ✅ Accepted | | 0009 | BDD Testing with OpenAPI Documentation | ✅ Accepted |
| 0010 | CI/CD Pipeline Design | ✅ Accepted | | 0010 | API v2 Feature Flag | ✅ Accepted |
| 0011 | Trunk-Based Development | ✅ Accepted | | 0011 | Validation Library (go-playground/validator) | ✅ Accepted |
| 0012 | Commit Message Conventions | ✅ Accepted | | 0012 | Git Hooks: Staged-Only Formatting | ✅ Accepted |
| 0013 | Version Management Lifecycle | ✅ Accepted | | 0013 | OpenAPI/Swagger Toolchain (swaggo/swag) | ✅ Accepted |
| 0014 | Swagger Documentation | ✅ Accepted | | 0014 | gRPC Adoption Strategy | ❌ Rejected / Deferred |
| 0015 | Rate Limiting Strategy | ✅ Accepted | | 0015 | CLI Subcommands with Cobra | ✅ Accepted |
| 0016 | Cache Invalidation Strategy | ✅ Accepted | | 0016 | CI/CD Pipeline Design | ✅ Accepted |
| 0017 | JWT Secret Rotation | ✅ Accepted | | 0017 | Trunk-Based Development Workflow | ✅ Accepted |
| 0018 | Configuration Hot Reloading | ✅ Accepted | | 0018 | User Management and Auth System | ✅ Accepted |
| 0019 | BDD Feature Structure | ✅ Accepted | | 0019 | PostgreSQL Integration | ✅ Accepted (SQLite cleanup pending) |
| 0020 | Database Migration Strategy | ✅ Accepted | | 0020 | Docker Build Strategy | ✅ Accepted |
| 0021 | API Versioning Strategy | ✅ Accepted | | 0021 | JWT Secret Retention Policy | 🟡 Proposed (base JWT done; cleanup job not implemented) |
| 0022 | Rate Limiting and Cache Strategy | ✅ Accepted | | 0022 | Rate Limiting and Cache Strategy | 🟡 Proposed (not implemented — Gitea issue #13) |
| 0023 | Config Hot Reloading | 🟡 Proposed | | 0023 | Config Hot Reloading | 🟡 Proposed (not implemented) |
| 0024 | BDD Test Organization and Isolation | 🟡 Proposed | | 0024 | BDD Test Organization and Isolation | ✅ Accepted |
| 0025 | BDD Scenario Isolation Strategies | 🟡 Proposed | | 0025 | BDD Scenario Isolation Strategies | ✅ Accepted (Partial — Phase 2 pending ADR-0022) |
## What is an ADR? ## What is an ADR?
@@ -96,23 +96,24 @@ Chosen option: "[Option 1]" because [justification]
* [0005-graceful-shutdown.md](0005-graceful-shutdown.md) - Implement graceful shutdown with readiness endpoints * [0005-graceful-shutdown.md](0005-graceful-shutdown.md) - Implement graceful shutdown with readiness endpoints
* [0006-configuration-management.md](0006-configuration-management.md) - Use Viper for configuration management * [0006-configuration-management.md](0006-configuration-management.md) - Use Viper for configuration management
* [0007-opentelemetry-integration.md](0007-opentelemetry-integration.md) - Integrate OpenTelemetry for distributed tracing * [0007-opentelemetry-integration.md](0007-opentelemetry-integration.md) - Integrate OpenTelemetry for distributed tracing
* [0008-bdd-testing.md](0008-bdd-testing.md) - Adopt BDD with Godog for behavioral testing * [0008-bdd-testing.md](0008-bdd-testing.md) - Adopt BDD with Godog for behavioral testing (structure superseded by 0024)
* [0009-hybrid-testing-approach.md](0009-hybrid-testing-approach.md) - Combine BDD and Swagger-based testing * [0009-hybrid-testing-approach.md](0009-hybrid-testing-approach.md) - BDD testing with OpenAPI documentation (SDK layer deferred)
* [0010-api-v2-feature-flag.md](0010-api-v2-feature-flag.md) - API v2 implementation with feature flag control * [0010-api-v2-feature-flag.md](0010-api-v2-feature-flag.md) - API v2 implementation with feature flag control
* [0011-validation-library-selection.md](0011-validation-library-selection.md) - Selection of go-playground/validator for input validation * [0011-validation-library-selection.md](0011-validation-library-selection.md) - Selection of go-playground/validator for input validation
* [0012-git-hooks-staged-only-formatting.md](0012-git-hooks-staged-only-formatting.md) - Git hooks format only staged Go files * [0012-git-hooks-staged-only-formatting.md](0012-git-hooks-staged-only-formatting.md) - Git hooks format only staged Go files
* [0013-openapi-swagger-toolchain.md](0013-openapi-swagger-toolchain.md) - ✅ OpenAPI/Swagger documentation with swaggo/swag (Implemented) * [0013-openapi-swagger-toolchain.md](0013-openapi-swagger-toolchain.md) - OpenAPI/Swagger documentation with swaggo/swag
* [0014-grpc-adoption-strategy.md](0014-grpc-adoption-strategy.md) - Hybrid REST/gRPC adoption strategy * [0014-grpc-adoption-strategy.md](0014-grpc-adoption-strategy.md) - gRPC adoption strategy (rejected/deferred)
* [0015-cli-subcommands-cobra.md](0015-cli-subcommands-cobra.md) - Cobra CLI framework adoption * [0015-cli-subcommands-cobra.md](0015-cli-subcommands-cobra.md) - Cobra CLI framework adoption
* [0016-ci-cd-pipeline-design.md](0016-ci-cd-pipeline-design.md) - CI/CD pipeline architecture * [0016-ci-cd-pipeline-design.md](0016-ci-cd-pipeline-design.md) - CI/CD pipeline architecture
* [0017-trunk-based-development-workflow.md](0017-trunk-based-development-workflow.md) - Trunk-based development workflow * [0017-trunk-based-development-workflow.md](0017-trunk-based-development-workflow.md) - Trunk-based development workflow
* [0018-user-management-auth-system.md](0018-user-management-auth-system.md) - User management and authentication system * [0018-user-management-auth-system.md](0018-user-management-auth-system.md) - User management and authentication system
* [0019-postgresql-integration.md](0019-postgresql-integration.md) - PostgreSQL database integration * [0019-postgresql-integration.md](0019-postgresql-integration.md) - PostgreSQL database integration
* [0020-docker-build-strategy.md](0020-docker-build-strategy.md) - Docker Build Strategy: Traditional vs Buildx * [0020-docker-build-strategy.md](0020-docker-build-strategy.md) - Docker Build Strategy: Traditional vs Buildx
* [0021-jwt-secret-retention-policy.md](0021-jwt-secret-retention-policy.md) - JWT Secret Retention Policy with Configurable TTL and Retention * [0021-jwt-secret-retention-policy.md](0021-jwt-secret-retention-policy.md) - JWT Secret Retention Policy (base JWT done; cleanup job proposed)
* [0022-rate-limiting-cache-strategy.md](0022-rate-limiting-cache-strategy.md) - Rate Limiting and Cache Strategy with Multi-Phase Implementation * [0022-rate-limiting-cache-strategy.md](0022-rate-limiting-cache-strategy.md) - Rate Limiting and Cache Strategy (not yet implemented — issue #13)
* [0023-config-hot-reloading.md](0023-config-hot-reloading.md) - Config Hot Reloading Strategy * [0023-config-hot-reloading.md](0023-config-hot-reloading.md) - Config Hot Reloading Strategy (not yet implemented)
* [0025-bdd-scenario-isolation-strategies.md](0025-bdd-scenario-isolation-strategies.md) - Schema-per-scenario isolation for BDD tests * [0024-bdd-test-organization-and-isolation.md](0024-bdd-test-organization-and-isolation.md) - BDD test modular organisation by domain
* [0025-bdd-scenario-isolation-strategies.md](0025-bdd-scenario-isolation-strategies.md) - Schema-per-scenario isolation for BDD tests (partial)
## How to Add a New ADR ## How to Add a New ADR