Project Structure

RetailOS adalah monorepo yang berisi seluruh backend (Go), frontend web (TypeScript), mobile apps (Expo), dan dokumentasi.

Top-Level Layout

retailos/
├── cmd/                        ← Go entry points
│   ├── cloud-hub/main.go       Cloud Hub binary
│   ├── store-router/main.go    Store Router binary
│   └── dc-edge/main.go         DC Edge binary
│
├── internal/                   ← Go business logic (private packages)
│   ├── auth/                   Service-to-service authentication
│   ├── cloud/                  Cloud Hub modules
│   │   ├── accounting/         Double-entry accounting
│   │   ├── analytics/          KPI & trend analysis
│   │   ├── approval/           Multi-level approval workflow
│   │   ├── audit/              Audit logging
│   │   ├── commercial/         Pricing, promotions, margins
│   │   ├── customer/           Customer profiles & purchase history
│   │   ├── db/                 PostgreSQL connection & migrations
│   │   ├── events/             Event processing
│   │   ├── finance/            Settlement, bank recon, AR/AP
│   │   ├── hr/                 Employee management
│   │   ├── identity/           User CRUD, JWT, roles
│   │   ├── masterdata/         Products, categories, stores
│   │   ├── metrics/            Prometheus metrics
│   │   ├── monitoring/         Store health monitoring
│   │   ├── payroll/            Salary calculation
│   │   ├── procurement/        PO, goods receiving
│   │   ├── push/               Push notifications
│   │   ├── reports/            Report generation, Excel export
│   │   ├── router/             HTTP router assembly
│   │   ├── storeops/           Store operations data
│   │   ├── tax/                Tax rates & invoices
│   │   └── webhook/            Webhook delivery
│   ├── store/                  Store Router modules
│   │   ├── cashops/            Petty cash, deposits, settlement
│   │   ├── commands/           Command processing from cloud
│   │   ├── dailyrecon/         End-of-day reconciliation
│   │   ├── dashboard/          Store manager dashboard
│   │   ├── eventlog/           Event log management
│   │   ├── inventory/          Local stock management
│   │   ├── loyalty/            Points calculation
│   │   ├── mqttbroker/         Embedded MQTT broker
│   │   ├── opname/             Stock opname
│   │   ├── pos/                POS engine (transactions, payments, returns)
│   │   ├── pricing/            Price lookup
│   │   ├── promo/              Promo rule evaluation
│   │   ├── receiving/          Goods receiving
│   │   ├── reconciliation/     3-way cash reconciliation
│   │   ├── router/             HTTP router assembly
│   │   ├── storesession/       Store open/close
│   │   ├── syncagent/          Cloud sync engine
│   │   └── transfer/           Stock transfers
│   └── dc/                     DC Edge modules
│       ├── packing/            Pack verification
│       ├── picking/            Wave picking
│       ├── router/             HTTP router
│       └── sync/               DC sync agent
│
├── pkg/                        ← Go shared packages (importable)
│   ├── config/                 Configuration structs
│   ├── crypto/                 HMAC, hashing utilities
│   ├── dbmigrate/              Database migration runner
│   ├── envelope/               Event envelope types
│   ├── health/                 Health check framework
│   ├── observability/          Logging, metrics setup
│   ├── schema/                 JSON schema validation
│   └── uuidv7/                 UUIDv7 generator
│
├── migrations/                 ← SQL migration files
│   ├── cloud/                  PostgreSQL (13 files)
│   ├── store/                  SQLite (26 files)
│   └── dc/                     SQLite (4 files)
│
├── pos-electron/               ← POS Desktop Application
│   ├── main/                   Electron main process
│   └── renderer/               React frontend (TanStack Router)
│
├── ho-finance/                 ← HO Finance Portal
├── store-admin/                ← Store Admin Portal
├── hr-portal/                  ← HR Portal
├── purchasing-portal/          ← Purchasing Portal
├── finance-portal/             ← Finance Portal
├── ga-portal/                  ← General Affairs Portal
├── promo-portal/               ← Promo Portal
│
├── stock-app-mobile/           ← Stock App (Expo)
├── customer-app/               ← Customer App (Expo)
├── buyer-app/                  ← Buyer App (Expo)
│
├── docs/                       ← Documentation (VitePress)
├── deploy/                     ← Deployment scripts
│   ├── fresh-server/           4-step deploy scripts
│   ├── alibaba/                Alibaba Cloud config
│   └── store/                  Store deployment
│
├── test/                       ← E2E tests
│   └── e2e/                    Go e2e test files
│
├── go.mod                      Go module definition
├── go.sum                      Go dependency checksums
└── docker-compose.yml          Dev/staging Docker Compose

Konvensi Penamaan

Item	Konvensi	Contoh
Go packages	lowercase singular	accounting, pos, transfer
Go files	snake_case	purchase_orders.go, daily_recon.go
Go types	PascalCase	TransactionManager, Handlers
Migration files	numbered prefix	001_master_data.sql, 004_pos.sql
Portal directories	kebab-case	ho-finance, store-admin
React components	PascalCase files	PaymentPanel.tsx, ShiftClose.tsx
API routes	kebab-case	/api/pos/transactions, /api/daily-recon

Module Organization Pattern

Setiap module backend (di internal/cloud/ atau internal/store/) mengikuti pattern:

{module}/
├── handler.go       ← HTTP handlers (Handlers struct)
├── service.go       ← Business logic
├── types.go         ← Request/response types
├── {module}_test.go ← Unit tests
└── {extra}.go       ← Additional logic files

Contoh internal/store/pos/:

pos/
├── session.go       ← Shift management (open/close)
├── transaction.go   ← Transaction lifecycle
├── payment.go       ← Payment processing
├── discount.go      ← Discount calculations
├── member.go        ← Member lookup & points
├── returns.go       ← Return processing
├── types.go         ← All type definitions
└── pos_test.go      ← Tests