shop-backend/developer_doc/pre_design/robot-market-backend-dir-plan-updated.md

Robot Market Backend Plan (Updated)

Final decisions

Stack

• Go backend
• Gin HTTP framework
• PostgreSQL
• pgx/v5
• sqlc
• golang-migrate
• Cobra CLI

Architecture

Lightweight hexagonal / domain-oriented architecture.

Flow:

REST (Gin) → Handler → Service → Domain → Repository interface → PostgreSQL adapter → sqlc → pgx/v5 → PostgreSQL

Rules: - Business logic stays in feature packages. - HTTP concerns stay in internal/http. - sqlc generated models do not leak into domain packages. - Repository interfaces belong to the feature consuming them. - Shared packages are created only when a real cross-cutting need appears.

DTO convention

Each feature owns dto.go.

Example:

internal/order/

• domain.go
• dto.go
• service.go
• repository.go
• errors.go

Naming:

• CreateOrderReq
• CreateOrderResp
• UpdateOrderReq
• UpdateOrderResp

DTOs represent REST/application boundaries and contain JSON tags. Services convert DTOs to and from domain entities.

User model

User identity is introduced from Phase 1.

User: - authentication identity - role

Roles: - Customer - Admin - Owner

Customer profile is a later feature.

Admin and Owner are roles, not separate entities.

Directory structure

backend/
├── cmd/
│   ├── api/
│   │   └── main.go
│   └── cli/
│       └── main.go
│
├── internal/
│   ├── app/
│   │   ├── app.go
│   │   └── config.go
│   │
│   ├── command/
│   │   ├── root.go
│   │   ├── admin.go
│   │   └── seed.go
│   │
│   ├── user/
│   │   ├── domain.go
│   │   ├── repository.go
│   │   └── errors.go
│   │
│   ├── auth/
│   │   ├── dto.go
│   │   ├── service.go
│   │   └── errors.go
│   │
│   ├── catalog/
│   │   ├── domain.go
│   │   ├── dto.go
│   │   ├── service.go
│   │   ├── repository.go
│   │   └── errors.go
│   │
│   ├── http/
│   │   ├── server.go
│   │   ├── config.go
│   │   ├── handler/
│   │   ├── route/
│   │   └── middleware/
│   │
│   └── postgres/
│       ├── db.go
│       ├── user.go
│       ├── auth.go
│       ├── catalog.go
│       ├── query/
│       └── sqlc/
│
├── pkg/
│   ├── apperr/
│   └── log/
│
├── integration/
│   ├── auth/
│   ├── catalog/
│   └── testutil/
│
├── migrations/
├── sqlc.yaml
├── Makefile
├── go.mod
└── go.sum

App instantiation

internal/app is the composition root.

Responsibilities: - load config - initialize database - create repositories - create services - create handlers - create Gin server - manage lifecycle

cmd/api/main.go remains thin.

CLI

Cobra is used for application commands.

CLI handles: - admin bootstrap - seed data - maintenance commands

Business logic remains in feature services.

HTTP

Use gin.New() instead of gin.Default().

The application owns: - logging middleware - recovery middleware - request ID middleware - authentication middleware

Database

Migration source of truth:

migrations/ → golang-migrate → PostgreSQL

Query generation:

PostgreSQL → sqlc → generated code → repository adapters

Generated sqlc code stays inside internal/postgres/sqlc.

Testing

Unit tests: - beside implementation - domain and service tests - mocks/fakes allowed

Integration tests: - focus on service layer - use real PostgreSQL

Flow:

Service → Repository → sqlc → pgx → PostgreSQL

Directory:

integration/ - auth/ - catalog/ - testutil/

Phase 1

Includes: - user identity - admin authentication - role authorization - catalog management: - products - modules - pricing - specifications - product-module relations

Later: - customer profiles - cart - orders - payment - wallet