🌐 dotFlat — DeFi Frontend

Full-stack frontend for the dotFlat collateralized stablecoin protocol.
Users manage CDP positions, deposits, auctions, and liquidity pools — all backed by a Redis-cached contract layer and a real-time block-watcher service.

---

🏗️ Architecture

                    Browser
                       │
              ┌────────┴────────┐
              │   Nginx / React  │  :8008 (prod) · :3000 (dev)
              └────────┬────────┘
                       │
         ┌─────────────┼──────────────┐
         │             │              │
    /api/contracts  /api/worker   /api/rpc
         │             │              │
         ▼             ▼              ▼
  ┌────────────┐ ┌───────────┐  Ethereum RPC
  │  Backend   │ │  Block    │  (publicnode /
  │  Express   │ │  Watcher  │   Infura / etc)
  │  :3001     │ │  :3002    │
  └─────┬──────┘ └─────┬─────┘
        │               │ WebSocket
        └───────┬────────┘
                ▼
          ┌──────────┐
          │  Redis   │  60s TTL · auto-invalidated on tx
          │  :6379   │
          └──────────┘

🧩 Services

Service	Port	Description
Frontend	8008 / 3000	React 19 SPA served by Nginx in prod, CRA dev server locally
Backend	3001	Express API — aggregates contract reads, serves cached responses
Block Watcher	3002 / 3003	Monitors new blocks via WebSocket, invalidates Redis on tx
Redis	6379	Shared cache — TTL 60s, write-through invalidation by watcher

🔑 Key Design Decisions

• 📡 WebSocket block monitoring — 1 subscription replaces N×polling; 50× RPC load reduction
• 💾 Three-layer cache — component state → Redis (60s TTL, auto-invalidated) → Ethereum RPC
• 🔒 Circuit breaker — workerCircuitBreaker.js degrades gracefully when the watcher is unavailable
• 🌐 Nginx RPC proxy — /api/rpc solves browser CORS and enables future server-side caching
• ⚡ Lazy-loaded pages — React Suspense + code splitting for fast initial load
• 🔄 DAO-gated contract calls — only authorized addresses can mutate; all reads go through cache

🛠️ Tech Stack

🚀 Getting Started

Docker Compose (recommended)

# Development — hot reload, production-like RPC proxy
docker compose --profile dev up -d
# → http://localhost:3008

# Development LOCAL — hot reload against a local Ganache/Hardhat node (:8545)
docker compose --profile dev-local up -d
# → http://localhost:3007

# Production — optimized build + full stack (frontend, backend, watcher, redis)
docker compose --profile prod up -d
# → http://localhost:8008

# Workers only — block-watcher + redis, no frontend
docker compose --profile workers up
# health: http://localhost:3002/health

Native

npm install
npm start          # dev server → http://localhost:3000
npm run build      # production build → /build
npm test           # jest test runner

⚙️ Environment Variables

Copy .env.example to .env and adjust:

Variable	Default	Purpose
REACT_APP_ETHERSCAN_API_KEY	—	ETH price fetch via Etherscan
REACT_APP_WALLETCONNECT_PROJECT_ID	—	WalletConnect modal
REACT_APP_RPC_URL	/api/rpc	RPC endpoint (proxied or direct URL)
REACT_APP_WORKERS_HEALTH_URL	/api/worker/health	Block watcher health endpoint
RPC_WS_URL	wss://ethereum.publicnode.com	Block watcher WebSocket RPC
RPC_HTTP_URL	https://ethereum.publicnode.com	Block watcher HTTP RPC
START_BLOCK	21677704	Block watcher indexing start
ETHERSCAN_API_KEY	—	ABI fetching for watched contracts
CACHE_TTL	60	Redis TTL in seconds
LOG_LEVEL	info	Backend / watcher log level

🌐 Smart Contracts (Ethereum Mainnet)

Contract	Address
INTDAO (governance)	0x55Ead3b40016b1d5417F5A20F2d1E53e2d1c9122
CDP	0xbCf58DE37791eFe60fE87a6d420FE8F7AEA99ef8
flatCoin (DFC, ERC-20)	0x1F709Cfa0C409E158C68EdcD32453809c9Eb69EE
Deposit	0x44881F5ac2938AAaF4260d7DBE18997318788f9f
Auction	0xBdFb52d4C9fBdE41805abBb206465aca3b3499D6
Rule Token (RLE)	0x3Dfa45997ddB7980Eb4D73CBfCf0E024F05b08a3
Exchange Rate	0x1DF609afDC67396a9f307de2BA3E3b667dEe8b5B

Full contract config: src/utils/config.js

🚢 Deployment

CI/CD via GitLab pipeline (.gitlab-ci.yml):

• Build — Kaniko (containerless) → GitLab Container Registry
• develop branch → auto-deploy to beta.app.dotflat.io
• master branch → auto-deploy to app.dotflat.io
• Orchestration: Kubernetes (K3s), rolling updates via kubectl set image

See k8s/README.md for cluster setup notes (Redis namespace, FQDN config).

🗺️ Roadmap

See ROADMAP.md.

📚 Documentation

• Quick Start — choosing the right dev mode
• Docker Setup — Compose profiles explained
• Workers — block-watcher architecture deep dive
• Block Watcher Page — cache inspection UI
• RPC Proxy — CORS solution and proxy config
• Caching — three-layer cache strategy
• Routing — client-side routing and deep linking
• Event Fetching — block range limit workarounds
• Uniswap Integration — swap/pool logic
• Oracle — commodities price feed system