senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/veza-docs/adr/ADR-005-handler-architecture.md
senke e4dd09a909
Some checks failed
Backend API CI / test-unit (push) Failing after 0s
Details
Backend API CI / test-integration (push) Failing after 0s
Details
feat(v0.13.0): conformité features partielles — CAPTCHA, password history, login history, SMS 2FA 
TASK-CONF-001: SMS 2FA service (sms_2fa_service.go) — SMSProvider interface,
  rate limiting (3/h), 6-digit codes, 5min expiry, LogSMSProvider for dev.
TASK-CONF-002: CAPTCHA service (captcha_service.go) — Cloudflare Turnstile
  verification with fail-open + RequireCaptcha middleware. 11 tests.
TASK-CONF-003: Auth features completed:
  - F014 password history (password_history_service.go) — checks last 5 hashes,
    integrated into PasswordService.ChangePassword. 3 tests.
  - F024 login history (login_history_service.go) — Record, GetUserHistory,
    CountRecentFailures for security auditing.
  - F010/F013/F018/F021/F026 verified already implemented.
TASK-CONF-004: F075 ClamAV verified implemented. F080 watermark deferred (P4).
TASK-CONF-005: ADR-005 handler architecture documented (keep dual, migrate forward).
TASK-CONF-006: Frontend 0 TODO/FIXME, backend 1 — criteria met.

Migration: 970_password_login_history_v0130.sql (password_history, login_history,
sms_verification_codes tables).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-12 09:31:50 +01:00

1.6 KiB
Raw Blame History

ADR-005: Handler Architecture (dual structure)

Status: Accepted Date: 2026-03-12 Context: v0.13.0 TASK-CONF-005

Context

The codebase has two handler locations:

  1. internal/handlers/ — Legacy flat structure (132 files, ~36K LoC)

    • Used by: auth, profiles, social, chat, analytics, marketplace
    • Pattern: func (h *XxxHandler) Method(c *gin.Context)

  2. internal/core/*/handler.go — Modular structure (7 packages)

    • Used by: admin, analytics, auth, discover, feed, moderation, track
    • Pattern: domain-driven package with handler + service + types

  3. internal/api/handlers/ — API-specific handlers (4 files)

    • Used by: RBAC, chat, 2FA

Decision

Keep both structures with a gradual migration path:

  • New features (v0.13.0+) must use internal/core/*/ modular pattern
  • Existing handlers in internal/handlers/ are NOT refactored unless touched for other reasons
  • No duplicate handlers — if a handler exists in core/, the legacy version should redirect or be removed

Rationale

  1. A full migration of 132 files would be high-risk with no user-facing value
  2. The modular pattern is better for testability (interfaces, dependency injection)
  3. Both patterns use the same Gin framework and middleware stack
  4. Routes are defined in internal/api/routes_*.go — the router doesn't care where handlers live

Consequences

  • New developers should look in internal/core/*/ first for newer features
  • Legacy handlers remain functional and tested
  • Route files in internal/api/ serve as the single source of truth for endpoint mapping