# 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