NAM-APJATEL-BACKEND/AGENTS.md

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

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