How bigcompany/safewallet works
Project type and purpose
• This is a full-stack, microservices-based Node.js application (“SafeWallet”) that implements an open-source crypto-currency “bank.”
• It consists of three core services (frontend, deposits, withdrawals), plus a monitoring service, all relying on a shared CouchDB ledger, external blockchain networks, and an offline “cold-wallet” pool.
File structure
• bin/ (entrypoints):
– bin/frontend → starts the web UI service (Express + View + Resource)
– bin/deposits → starts the deposit processing service (blockchain listener → move to cold wallet → update DB)
– bin/withdrawals → starts the withdrawal processing service (queue processor + security checks)
– bin/monitor → starts the central monitoring server
• lib/ (business logic):
– lib/frontend → routes, views, public assets, email hooks, middleware
– lib/deposits → blockchain-integration, DB-write hooks
– lib/withdrawals → payout logic, manual-approval hooks
– lib/monitoring/agent.js + server.js → host agent and central collector
– lib/resources → shared REST resource definitions (users, wallets, ledger, prices, metrics, etc.)
• config/ (environment settings), components/ (third-party modules), scripts/ (cron jobs, alerts, startup scripts), logs/, test/, docs/
Key architectural insights from README
• Three isolated services for security hardening
• CouchDB ledger with revision history as the single source of truth
• Cold-wallet pool (offline) protected by physical security, “hot-wallet” used briefly for transactions
• Event-driven hooks update ledger & send email notifications
• Manual process: bring an offline wallet online to service withdrawals
Main components
a. Frontend Web Service
– Express.js + Resource + View + JugglingDB → serves user UI, REST API, sessions, email notifications
– Public assets (JS/CSS), templates, client-side MVC
b. Account Deposits Service
– Listens to blockchain explorer or full node for incoming transactions
– Updates CouchDB ledger, then immediately transfers coins from hot-wallet to cold-wallet
c. Account Withdrawals Service
– Consumes withdrawal requests from DB queue
– Enforces multi-factor security checks (email, voice/video) via hooks
– Requires manual bring-online of an offline wallet to drain funds
d. Monitoring Service
– Host-level agent → collects metrics (CPU, memory, custom app metrics) → central monitoring server
– Alerts via scripts/alerts/*
e. CouchDB Ledger (shared)
– Stores users, wallets, transactions, revision history
f. Cold-Wallet Pool (offline)
– Physically secured machines/hardware wallets, not network-connected
g. External Services & Networks
– Crypto networks (Bitcoin, Peercoin) via explorers or full nodes
– SMTP/email provider
– Price feeds (scripts/prices)
Relationships and data flows
• User → Frontend Web Service → CouchDB (REST API)
• Frontend triggers deposits (not directly) but users see balances from CouchDB
• Deposit Service ↔ Blockchain networks → hot-wallet → cold-wallet
• Deposit Service → CouchDB updates → user balances
• Withdrawal Service ← CouchDB withdrawal requests → security hooks → email/user & admin → manual wallet bring-online → blockchain networks
• Monitoring Agent → Monitoring Server → Alerts (scripts/alerts)
• Cron jobs (scripts/cron) → maintenance tasks (e.g., price updates, ledger cleanups)
Architectural patterns and design principles
• Microservices for isolation (one process per concern)
• Event-driven updates via CouchDB change-feeds and hook modules
• RESTful resource layer (lib/resources) decoupled from UI and background processors
• Separation of hot vs. cold storage to minimize online exposure
• Manual, audited workflows for high-value actions (withdrawals, cold wallet re-use)