ADR-001: Backend Architecture Unification

Status

Accepted — 2026-02-15

Context

The Veza backend API uses two architectural patterns:

Core (DDD-style): internal/core/track/, internal/core/auth/, internal/core/marketplace/, internal/core/social/ — handlers and services colocated per domain
Legacy (flat handlers): internal/handlers/ — analytics_handler, playlist_handler, comment_handler, playback_analytics_handler, etc.

This inconsistency creates confusion for developers and makes it unclear where new code should live.

Decision

Option A: Migrate all handlers to internal/core/ (domain-driven structure).

We choose Option A for long-term consistency with the existing core domains (track, auth, marketplace, social). New features will follow the same pattern.

Migration Strategy

Incremental migration — One domain at a time, with tests passing after each step
Order of migration (by priority and coupling):
- ✅ analytics_handler → internal/core/analytics/ (completed 2026-02-15)
- playback_analytics_handler → internal/core/playback/ (or integrate into track)
- playlist_handler → internal/core/playlist/
- comment_handler → internal/core/comment/ (or integrate into track)
- room_handler, session → internal/core/chat/ or internal/core/session/
- health.go, upload.go, bitrate_handler — evaluate per ADR update
Service layer — Handlers in core use existing internal/services/* packages; no new service packages unless domain logic warrants it
Response helpers — Core handlers continue to use handlers.RespondWithAppError, handlers.RespondSuccess from the handlers package (shared HTTP utilities)

Consequences

Positive: Single, consistent architecture; easier onboarding
Negative: Migration effort; temporary coexistence of both patterns during transition
Risk: Breaking changes if imports are not updated correctly — mitigate with go build ./... and tests after each migration

References

veza-backend-api/README.md — Patterns section
docs/archive/AUDIT_TECHNIQUE_INTEGRAL_2026_02_15.md — Phase 3 plan

2.2 KiB Raw Blame History