doc:added dir plan doc and gitignore

2026-09-17 10:31:30 +03:30
parent a392bc1334
commit a8d3be0ccd
3 changed files with 194 additions and 0 deletions
@@ -0,0 +1,190 @@
+# 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