# 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