# PROJECT KNOWLEDGE BASE

**Generated:** 2026-04-11
**Commit:** 3d5ce0d
**Branch:** dev

## OVERVIEW
Go backend API for telecom network asset management (NAM). Manages ODP/OTB/OLT/Tower infrastructure with Gin + GORM.

## STRUCTURE
```
backend_nam/
├── config/         # Environment config (DB, JWT, API)
├── delivery/       # HTTP layer (server.go, controllers/)
├── manager/        # Dependency injection wiring
├── middleware/    # Auth, CORS, RBAC, rate limiting, logging
├── model/         # DTOs (req/res) + Entities
├── repository/    # Database operations
├── usecase/       # Business logic
├── utils/         # Helpers, services, migrations, common
├── main.go        # Entry point
└── go.mod
```

## WHERE TO LOOK
| Task | Location | Notes |
|------|----------|-------|
| Add API endpoint | delivery/controller/ | New {name}_controller.go |
| Business logic | usecase/ | New {name}_usecase.go |
| DB operations | repository/ | New {name}_repo.go |
| Data models | model/entity/ | GORM structs |
| Config changes | config/config.go | env vars |

## CONVENTIONS
- **Package path**: `users_management/m/...`
- **File naming**: snake_case (`device_usecase.go`)
- **Interface naming**: `{Entity}Repo`, `{Entity}UseCase`
- **Constructor**: `New{Entity}{Layer}(deps) *{entity}{Layer}`
- **GORM tags**: `json:"field" gorm:"type:uuid;primaryKey"`
- **Response format**: `common.SingleResponses(c, "message", data)`
- **Error format**: `common.ErrorResponses(c, http.StatusBadRequest, "message")`

## ANTI-PATTERNS (THIS PROJECT)
- **DO NOT** use `as any` - strict typing required
- **DO NOT** skip validation in usecases - use `validator.New()`
- **DO NOT** commit `.env` files
- **DO NOT** hardcode file paths - use constants in helper/

## UNIQUE STYLES
- **Auth middleware**: Conditional based on `USER_AUTH_ENABLED` env var
- **Image handling**: Local filesystem at `./uploads/` + `/uploads/` static route
- **Bulk operations**: Return `{Successful, Failed, TotalRequested, Errors[], Results[]}`
- **DevicePort auto-create**: Created automatically when Device is created

## COMMANDS
```bash
go run main.go                    # Local dev
go build -o main .                 # Build binary
docker build -t nam-backend .      # Docker build
go test ./...                      # Run all tests
go test -v ./usecase/...          # Run usecase tests
```

## NOTES
- Port: `:5678` (Dockerfile EXPOSE)
- UUID primary keys everywhere
- Geocoding service with caching layer
- Activity logging middleware captures all mutations