# bigcompany/safewallet architecture

> Architecture diagram of the GitHub repository bigcompany/safewallet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bigcompany/safewallet
- Repository: https://github.com/bigcompany/safewallet

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    User["User"]:::external -->|HTTP/REST| FE

    subgraph "DMZ"
        FE["Frontend Web Service<br/>(Node.js/Express)"]:::service
    end

    subgraph "Backend"
        DP["Deposits Service<br/>(Blockchain Listener)"]:::service
        WD["Withdrawals Service<br/>(Queue & Security)"]:::service
        RL["REST Resource Layer<br/>(lib/resources)"]:::api
        DB["CouchDB Ledger"]:::database
    end

    subgraph "Monitoring Zone"
        MA["Monitoring Agent"]:::service
        MS["Monitoring Server"]:::service
        AL["Alerting Scripts"]:::script
    end

    subgraph "Air-gapped Zone"
        direction TB
        CW["Cold-Wallet Pool<br/>(Offline)"]:::offline
    end

    subgraph "External Systems"
        BC["Blockchain Networks"]:::external
        SMTP["SMTP/Email Provider"]:::external
    end

    subgraph "Cron & Startup Scripts"
        CF["Price Feeds"]:::script
        CJ["Cron Jobs"]:::script
        SS1["start-frontend.sh"]:::script
        SS2["start-deposits.sh"]:::script
        SS3["start-monitor.sh"]:::script
    end

    %% Data & Funds Flows
    FE -->|REST API Calls| RL
    RL -->|DB Read/Write| DB
    FE -->|Email Notifications| SMTP

    DP -->|DB Write| RL
    DP -->|Blockchain Listener| BC
    DP -->|Funds Flow: hot-wallet→cold-wallet| CW

    WD -->|DB Read: withdrawal requests| RL
    WD -->|Security Hooks| SMTP
    WD -->|Manual Process| CW
    WD -->|Blockchain Payout| BC

    MA -->|Metrics Collection| MS
    MS -->|Alerts Dispatch| AL

    CF -->|Price Updates| DB
    CJ -->|Maintenance Tasks| DB

    SS1 -->|Startup| FE
    SS2 -->|Startup| DP
    SS3 -->|Startup| MA

    %% Click Events
    click FE "https://github.com/bigcompany/safewallet/tree/master/bin/frontend"
    click FE "https://github.com/bigcompany/safewallet/tree/master/lib/frontend"
    click FE "https://github.com/bigcompany/safewallet/blob/master/lib/frontend/routes.js"
    click FE "https://github.com/bigcompany/safewallet/tree/master/lib/frontend/public"
    click FE "https://github.com/bigcompany/safewallet/tree/master/lib/frontend/view"

    click DP "https://github.com/bigcompany/safewallet/tree/master/bin/deposits"
    click DP "https://github.com/bigcompany/safewallet/blob/master/lib/deposits/index.js"

    click WD "https://github.com/bigcompany/safewallet/tree/master/bin/withdrawals"
    click WD "https://github.com/bigcompany/safewallet/blob/master/lib/withdrawals/index.js"

    click MA "https://github.com/bigcompany/safewallet/tree/master/bin/monitor"
    click MA "https://github.com/bigcompany/safewallet/blob/master/lib/monitoring/agent.js"

    click MS "https://github.com/bigcompany/safewallet/tree/master/bin/monitor"
    click MS "https://github.com/bigcompany/safewallet/blob/master/lib/monitoring/server.js"

    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/ledger.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/user.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/wallet.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/message.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/prices.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/metrics.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/explorers.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/vault.js"
    click RL "https://github.com/bigcompany/safewallet/blob/master/lib/resources/email.js"

    click CW "https://github.com/bigcompany/safewallet/blob/master/creating-offline-wallet.md"

    click BC "https://github.com/bigcompany/safewallet/blob/master/lib/deposits/index.js"
    click BC "https://github.com/bigcompany/safewallet/blob/master/lib/resources/explorers.js"

    click CF "https://github.com/bigcompany/safewallet/tree/master/scripts/prices/fetch-updated-prices"
    click AL "https://github.com/bigcompany/safewallet/tree/master/scripts/alerts"
    click CJ "https://github.com/bigcompany/safewallet/blob/master/scripts/cron/crontab.txt"

    click SS1 "https://github.com/bigcompany/safewallet/blob/master/scripts/start-frontend.sh"
    click SS2 "https://github.com/bigcompany/safewallet/blob/master/scripts/start-deposits.sh"
    click SS3 "https://github.com/bigcompany/safewallet/blob/master/scripts/start-monitor.sh"

    %% Styles
    classDef service fill:#c2f0c2,stroke:#2e8b57,color:#000
    classDef database fill:#cce5ff,stroke:#1f4e79,color:#000
    classDef external fill:#ffe5cc,stroke:#cc6600,color:#000
    classDef offline fill:#f2f2f2,stroke:#666,stroke-dasharray: 5 5,color:#000
    classDef api fill:#e6ccff,stroke:#7044a0,color:#000
    classDef script fill:#fff2cc,stroke:#d99900,color:#000
```
