Cloud Hub Architecture

Cloud Hub adalah backend utama RetailOS yang berjalan di kantor pusat. Ditulis dalam Go dengan database PostgreSQL, Cloud Hub mengelola semua data terpusat dan menerima event dari seluruh toko.

Overview

Entry Point

Cloud Hub di-bootstrap dari cmd/cloud-hub/main.go yang:

1. Membaca konfigurasi dari environment variables
2. Membuka koneksi ke PostgreSQL
3. Menjalankan migrasi database otomatis (dari migrations/cloud/*.sql)
4. Meng-instantiate semua handler module
5. Merakit Dependencies struct dan memanggil router.New(deps)
6. Start HTTP server pada port yang dikonfigurasi (default :8090)

Router Pattern

Cloud Hub menggunakan go-chi/chi/v5 sebagai HTTP router. Semua module handler di-inject melalui satu Dependencies struct:

type Dependencies struct {
    EventStore          EventStore
    CommandStore        CommandStore
    HealthChecker       *health.Checker
    APIKeys             map[string]bool
    ServiceAuthRegistry *serviceauth.ServiceRegistry
    WebhookManager      *webhook.Manager
    MasterdataHandler   *masterdata.Handler
    AccountingHandler   *accounting.Handlers
    FinanceHandler      *finance.Handler
    ProcurementHandler  *procurement.Handler
    HRHandler           *hr.Handlers
    TaxHandler          *tax.Handlers
    PayrollHandler      *payroll.Handlers
    // ... dan module lainnya
}

Pattern ini memastikan:

• Explicit dependencies -- Tidak ada global state
• Optional modules -- Field nil meng-disable module (feature flag gratis)
• Testability -- Mudah di-mock untuk unit test

Endpoint Structure

/live                         → Liveness probe
/ready                        → Readiness probe (checks DB)
/health                       → Health check endpoint
/metrics                      → Prometheus metrics

/stores/{store_id}/events     → Ingest event dari Store Router
/stores/{store_id}/commands   → Deliver commands ke Store Router

/api/v1/
  ├── events                  → Consumer event polling
  ├── consumers/              → Offset management
  ├── commands                → Issue commands to stores
  ├── webhooks                → Webhook subscription CRUD
  ├── masterdata/             → Products, categories, stores, suppliers
  ├── accounting/             → COA, journals, fiscal years, trial balance
  ├── finance/                → Settlement, bank reconciliation, AR/AP
  ├── procurement/            → PO, goods receiving, supplier performance
  ├── hr/                     → Employees, attendance, business trips
  ├── payroll/                → Salary calculation, payslips
  ├── tax/                    → Tax rates, invoices, reporting
  ├── commercial/             → Pricing, promotions, margins
  ├── identity/               → User CRUD, JWT login, role management
  ├── approval/               → Multi-level approval workflows
  ├── audit/                  → Audit log queries
  ├── monitoring/             → Store health, sync status
  ├── analytics/              → KPI dashboard, trend analysis
  ├── reports/                → Scheduled reports, Excel export
  ├── push/                   → Push notification management
  ├── storeops/               → Store operations data
  └── customer/               → Customer profile, purchase history

Middleware Stack

Setiap request melewati middleware chain berikut:

1. CORS -- Allow cross-origin dari portal web
2. RequestID -- Generate unique request ID (chi middleware)
3. RealIP -- Extract client IP dari proxy headers
4. Recoverer -- Catch panic, return 500
5. JWT Auth (optional) -- Extract claims dari Authorization: Bearer
6. API Key Auth -- Validate X-API-Key header per store

Event Ingest Pipeline

Ketika Store Router mengirim batch event ke /stores/{store_id}/events:

Module Pattern

Setiap module di Cloud Hub mengikuti pattern yang konsisten:

internal/cloud/{module}/
├── handler.go       -- HTTP handlers (Handlers struct)
├── service.go       -- Business logic
├── types.go         -- Request/response types
└── {module}_test.go -- Tests

Handler struct pattern:

type Handlers struct {
    db *sql.DB
}

func NewHandlers(db *sql.DB) *Handlers {
    return &Handlers{db: db}
}

func (h *Handlers) ListItems(w http.ResponseWriter, r *http.Request) {
    // ... handler implementation
}

Database

Cloud Hub menggunakan PostgreSQL 16 dengan fitur:

• Raw SQL -- Tidak menggunakan ORM, semua query ditulis langsung
• NUMERIC(18,4) -- Tipe data untuk semua nilai moneter (exact decimal)
• TIMESTAMPTZ -- Semua timestamp menyimpan timezone
• JSON columns -- Untuk data fleksibel (permissions, metadata)
• Migration files -- Sequential SQL files di migrations/cloud/

Lihat Cloud Schema untuk detail tabel.

Configuration

Environment Variable	Deskripsi	Default
CLOUD_DB_URL	PostgreSQL connection string	required
CLOUD_PORT	HTTP listen port	8090
JWT_SECRET	HMAC secret untuk JWT signing	required
API_KEYS	Comma-separated valid API keys	required
LOG_LEVEL	Zerolog log level	info
CORS_ORIGINS	Allowed CORS origins	*