SYSTEM_ARCHITECTURE.md

Garuda Chain Ecosystem — Arsitektur Sistem Keseluruhan

Metadata
Versi dokumen	1.0.0
Status	Living document
Production Chain ID	8846
Staging Chain ID	8847
Terakhir diperbarui	2026-07-04

---

1. Visi & Scope

Garuda Chain adalah Layer-1 EVM blockchain (Hyperledger Besu, IBFT 2.0) dengan ekosistem aplikasi:

• Garuda Wallet — Super App Web3 (dompet, payment, NFT, staking, bridge, community)
• Explorer — Block explorer publik
• API — Backend REST + GraphQL + RPC proxy
• Admin Monitor — Konsol operasional internal
• Smart Contracts — 17+ kontrak Solidity (GDC, PayHub, Bridge V2, GNFT, Staking, dll.)

Native coin: GDC · Chain ID production: 8846 · Kompatibilitas: EVM penuh

---

2. Topology Produksi

                    ┌─────────────────────────────────────────┐
                    │           Pengguna / Merchant            │
                    └───────────────┬─────────────────────────┘
                                    │
          ┌─────────────────────────┼─────────────────────────┐
          │                         │                         │
          ▼                         ▼                         ▼
  ┌───────────────┐        ┌───────────────┐        ┌───────────────┐
  │ Cloudflare    │        │ Caddy (TLS)   │        │ RPC Public    │
  │ Pages         │        │ VPS           │        │ rpc.garuda-   │
  │ wallet/admin  │        │ explorer/api  │        │ chainain.id   │
  └───────┬───────┘        └───────┬───────┘        └───────┬───────┘
          │                        │                        │
          └────────────────────────┼────────────────────────┘
                                   ▼
                    ┌─────────────────────────────────────────┐
                    │              VPS Production              │
                    │  ┌─────────┐ ┌──────────┐ ┌──────────┐  │
                    │  │ API     │ │ Explorer │ │ RPC-int  │  │
                    │  │ :4000   │ │ :3000    │ │ internal │  │
                    │  └────┬────┘ └────┬─────┘ └────┬─────┘  │
                    │       │           │            │         │
                    │  ┌────┴───────────┴────────────┴────┐   │
                    │  │     Besu Validators (×5 IBFT2)    │   │
                    │  │     + Anvil Rescue (GNFT/Bridge)  │   │
                    │  └───────────────────────────────────┘   │
                    └─────────────────────────────────────────┘
                                   │
                    ┌──────────────┴──────────────┐
                    │  Persistence (JSON files)   │
                    │  data/*.json                │
                    │  chain/community/*.json     │
                    └─────────────────────────────┘

URL Produksi

Layanan	URL
RPC	https://rpc.garudachain.id
API	https://api.garudachain.id
Explorer	https://explorer.garudachain.id
Wallet	https://wallet.garudachain.id
Admin	https://admin.garudachain.id
Docs	https://docs.garudachain.id
Landing	https://garudachain.id

URL Staging

Layanan	URL
RPC	https://rpc.staging.garudachain.id
API	https://api.staging.garudachain.id
Explorer	https://explorer.staging.garudachain.id
Wallet	https://wallet.staging.garudachain.id

---

3. Struktur Monorepo

Garuda Chain/
├── apps/                    # Aplikasi (13+)
│   ├── api/                 # REST + GraphQL backend
│   ├── wallet/              # Vite + React — dompet utama
│   ├── explorer/            # Next.js 14 — block explorer
│   ├── admin-monitor/       # Vite — konsol admin
│   ├── landing/             # Marketing site
│   ├── faucet/              # Testnet faucet
│   ├── rpc-public/          # Public RPC gateway
│   ├── rpc-gateway/         # Private RPC (API key)
│   ├── status/              # Health status page
│   ├── security-monitor/    # Anti-exploit monitoring
│   └── metrics-exporter/    # Prometheus exporter
├── packages/
│   └── sdk/                 # @garuda-chain/sdk — shared TS library
├── contracts/               # Foundry — Solidity ^0.8.24
├── chain/                   # Genesis, keys, deployments, bridge-config
├── scripts/                 # Deploy, mainnet, staging, production
├── deploy/                  # Build artifacts (wallet, docs, admin)
├── data/                    # Runtime JSON stores (API)
├── docs/                    # MkDocs documentation
└── docker-compose*.yml      # 8 compose files

Workspaces: packages/* + apps/* (npm workspaces)

---

4. Environment Matrix

Environment	Chain ID	Compose	Domain pattern
Devnet	8844	docker-compose.yml	localhost
Private testnet	8845	docker-compose.private.yml	localhost
Public testnet	8847	docker-compose.public.yml	rpc.testnet
Staging	8847	public.yml + staging.yml	*.staging.garudachain.id
Production	8846	mainnet.yml + production.yml	*.garudachain.id

Registry kontrak otoritatif: chain/deployments/{network}.json

---

5. Arsitektur Per Lapisan

5.1 Blockchain Layer

Komponen	Teknologi	Keterangan
Konsensus	Besu 24.12.2, IBFT 2.0	5 genesis validators, target 21
EVM	Berlin → Cancun @ block 0	Standard JSON-RPC
Native token	GDC (ERC-20 + permit)	0xadcfb…6ec8 mainnet
Stablecoin	GIDR (custodial IDR)	0 decimal, mint/burn by custodian
Bridge	GarudaBridge V2	Lock-and-mint, relayer off-chain
DEX	GarudaSimpleDEX	x*y=k AMM on hub
NFT	GarudaNFTMarketplace	ERC-721 GNFT (Garuda Digital Card)

Dual-RPC (penting):

RPC	Fungsi	Consumer
Besu consensus	Blocks, validators, consensus	Explorer, API umum
Anvil rescue	GNFT state, bridge hub activity	Wallet GNFT proxy, API /rpc/gnft

5.2 API Layer (apps/api)

Express 4 + TypeScript
├── src/index.ts          # Bootstrap, inline routes, middleware
├── routes/               # 11 route modules
│   ├── network.ts        # Chain config, GNFT public
│   ├── garudaPay.ts      # Payment rails
│   ├── kyc.ts            # KYC + admin review
│   ├── bridge.ts         # Bridge status, relay, sync
│   ├── community*.ts     # Rewards, missions, referral
│   ├── validators.ts     # Validator program
│   ├── admin.ts          # Admin dashboard
│   ├── wallet.ts         # Gas aid
│   └── rpcProxy*.ts      # JSON-RPC proxies
├── bridge/               # Relayer, indexer, fee automation (~15 files)
├── garudaPay/            # Store, settlement, fiat, CS
├── kyc/                  # Store, documents, on-chain verify
├── community/            # Check-in, missions, claims
├── auth/                 # EIP-191 wallet signatures
└── graphql/              # Schema + resolvers

Persistence: JSON files (bukan SQL) — lihat DATABASE_SCHEMA.md

Auth: - Admin: header x-admin-key - Wallet: EIP-191 signed message (production wajib)

5.3 Wallet Layer (apps/wallet)

Vite 6 + React 18
├── src/App.tsx              # Auth flow (welcome/create/import/unlock)
├── screens/MainWalletApp.tsx # Tab navigation + overlays
├── screens/                 # Dashboard, Market, Cards, Profile, Bridge, Pay
├── lib/ (~70 modules)       # chain, rpc, storage, garudaPay, gnft, bridge
├── components/              # UI, modals, flow screens
└── context/                 # i18n prefs, activity feedback

State: Screen state machine (bukan React Router). Tab: dashboard, market, invest, cards, profile.

Storage klien: - localStorage — encrypted wallet (PBKDF2 + AES-GCM), tx log, GNFT cache - sessionStorage — unlocked private key (12h), KYC draft, market cache

Deploy: Cloudflare Pages (wallet.garudachain.id)

5.4 Explorer Layer (apps/explorer)

Next.js 14 App Router
├── src/app/                 # Routes (blocks, txs, accounts, nfts, bridge, validators)
├── src/lib/chain.ts         # GarudaClient + multi-RPC + server cache
├── src/lib/nft.ts           # GNFT listings, metadata
└── src/app/api/live/        # Live chain feed (client polling)

Read-only — tidak ada private key. Server-side RPC dengan ISR/revalidate.

Deploy: Docker di VPS (garuda-explorer-prod)

5.5 Admin Monitor (apps/admin-monitor)

Vite + React — desktop console
├── pages/    Dashboard, KYC, Bridge, Validators, GarudaPay, Community, Tokenomics
└── lib/api.ts — adminFetch dengan x-admin-key (sessionStorage)

Deploy: Cloudflare Pages (admin.garudachain.id)

5.6 Shared SDK (packages/sdk)

Modul	Fungsi
config.ts	Chain definitions (8844–8847)
deployments.ts	Contract addresses per network
client.ts	GarudaClient — RPC wrapper
bridge*.ts	Bridge ABIs, fees, stages, event scan
wallet.ts, prime.ts	Wallet helpers, Prime app config

Catatan drift: deployments.ts dapat tidak sinkron dengan chain/deployments/mainnet.json. Lihat REFACTOR_PLAN.md.

---

6. Smart Contract Map (Mainnet)

Kontrak	Address	Peran
GDC	0xadcfb03225f09c67040e6e1387604486f86c6ec8	Native token
Treasury	0x53830d232377ca9a984b9c5f8ffb9d4b98c85b59	Dana treasury + multisig
PayHub	0x71f203d7c772677f036b3bbee505b4f883c522ef	Pembayaran merchant
Staking	0xbf523d6e312d68e4751d8025463c11b3fe1a5e95	Staking GDC
Governance	0xf5b4eee393aeba0c7a5faed0ca0d3d8b30dfefc9	Proposal on-chain
Identity	0x6b81ebc3a88b0cc4a1960b7deefb0d7d380acf5e	KYC/DID ERC-721
Validators	0x4228847e13e47d19f63d86e5a63f65960f869646	Validator registry
NFT Marketplace	0x2f5bEe60d40448015644B7CE0C73d6773F1f4247	GNFT
Bridge V2	0xe01933a009d519fE67fdcD6f86d666D03483F2ce	Cross-chain bridge
GIDR	0x1cd95b007f25ab497f65b89113f1aaafbd652b8c	IDR stablecoin
Community Claim	0x3e5daef2e2e33b0e9ef98b4574e46b918dec8a88	EIP-712 reward claims
DEX	0xdd32e33ca6db4092867b66b7e384724e0e7a32cf	Simple AMM
Wrapped tokens	14 addresses	wUSDT, wETH, wBNB, wBTC, dll.

---

7. Alur Data Utama

7.1 Transfer GDC (Wallet → Chain)

Wallet (ethers) → RPC (rpc.garudachain.id) → Besu validators → Block confirmed
              → appendTxLog (localStorage)

7.2 Garuda Pay Charge

Wallet → POST /garuda-pay/charge (wallet auth)
      → API settlement (GDC/GIDR on-chain + fiat ledger JSON)
      → Response txHash + payment record

7.3 GNFT Mint (KYC → NFT)

Wallet KYC submit → API kyc-store.json
Admin approve → on-chain Identity verify + mint NFT
Wallet → GNFT RPC proxy → Anvil rescue state

7.4 Bridge Outbound

Wallet lockOutbound on GarudaBridge
→ API indexer detects OutboundLocked event
→ Relayer sends USDT on ETH/BSC/Polygon
→ completeOutbound on hub

7.5 Community Check-in

Wallet → GET /check-in/prepare (nonce)
      → POST /check-in (wallet auth + nonce)
      → check-ins.json updated
      → Optional: claim via EIP-712 on CommunityRewardClaim contract

---

8. Deployment Pipeline

Local Dev (8844/8845)
    ↓ npm test, manual QA
Staging (8847, *.staging.garudachain.id)
    ↓ npm run staging:smoke, security review
Production (8846, *.garudachain.id)
    ↓ monitoring, rollback plan

Target	Perintah
API + Explorer VPS	bash scripts/production/deploy-api-vps.sh
Wallet Cloudflare	npm run wallet:deploy:cloudflare
Admin Cloudflare	bash scripts/admin-monitor/deploy-cloudflare.sh
Staging full	npm run staging:deploy

---

9. Monitoring & Observability

Tool	Fungsi
Prometheus + Grafana	Metrics chain & services
Loki	Log aggregation
Security Monitor	Large tx, watched contracts
Status page	Public health (status.garudachain.id)
API /health	Liveness probe

---

10. Arsitektur Target (Future-Ready)

Tanpa mengubah production saat ini, arsitektur target untuk skala jutaan pengguna:

┌─────────────────────────────────────────────────────────┐
│                  Garuda Platform Layer                     │
├─────────────┬─────────────┬─────────────┬───────────────┤
│ packages/   │ packages/   │ packages/   │ packages/     │
│ config      │ types       │ ui-core     │ wallet-auth   │
├─────────────┴─────────────┴─────────────┴───────────────┤
│ apps/api-v2 (Clean Architecture, PostgreSQL) — staging  │
├─────────────────────────────────────────────────────────┤
│ apps/wallet (Module Shell + lazy-loaded feature modules)  │
├─────────────────────────────────────────────────────────┤
│ chain/deployments/*.json ← Single Source of Truth       │
└─────────────────────────────────────────────────────────┘

Detail implementasi: lihat REFACTOR_PLAN.md dan PROJECT_ROADMAP.md.

---

11. Referensi Terkait

• PROJECT_ROADMAP.md
• API_DOCUMENTATION.md
• DATABASE_SCHEMA.md
• SECURITY_AUDIT.md
• REFACTOR_PLAN.md
• chain-overview.md
• production-deployment.md
• staging-deployment.md