davide
306f494cd8
- Dockerfile: node:20-alpine, compiles SCSS at build time, single image used for web server and all sync modes (blocks, peers, markets) - docker-compose.yml: explorer + MongoDB (bind-mounted ./db) on shared 'purple' network alongside bitcoinpurpled and electrumx - docker/entrypoint.sh: generates settings.json from env vars via envsubst, dispatches to web/sync-blocks/sync-peers/reindex modes - docker/settings.json.tmpl: minimal settings template parametrized for BitcoinPurple (coin, wallet RPC, MongoDB, theme) - docker/mongo-init.sh: creates app user in explorerdb on first start - .env.example: pre-filled defaults for BitcoinPurple - CLAUDE.md: codebase guidance for Claude Code - .gitignore: add db/ (MongoDB bind-mount data directory)
98 lines
3.8 KiB
Markdown
98 lines
3.8 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
**eIquidus** — a Node.js/Express blockchain block explorer for altcoins using the Bitcoin RPC protocol. It connects to a coin wallet via JSON-RPC, syncs blocks/transactions into MongoDB, and serves a web UI.
|
|
|
|
- Node.js ≥ 20.9.0, MongoDB ≥ 7.0.2
|
|
- Express v5, Pug templates, Mongoose ODM, Jasmine tests
|
|
- Configuration lives entirely in `settings.json` (created from `settings.json.template`)
|
|
|
|
## Common Commands
|
|
|
|
```bash
|
|
# Run tests
|
|
npm test # jasmine test/*Spec.js
|
|
|
|
# Start the explorer
|
|
npm start # cluster mode (1 worker per CPU)
|
|
npm run start-instance # single instance (dev/testing)
|
|
npm run start-pm2 # production via PM2
|
|
|
|
# Blockchain sync (run as separate processes, not part of the web server)
|
|
npm run sync-blocks # sync new blocks from wallet
|
|
npm run sync-markets # fetch exchange market data
|
|
npm run sync-peers # discover network peers
|
|
npm run sync-masternodes # update masternode list
|
|
npm run check-blocks # verify block integrity
|
|
|
|
# Database maintenance
|
|
npm run reindex # full reindex from wallet RPC
|
|
npm run create-backup # backup MongoDB
|
|
npm run restore-backup # restore MongoDB
|
|
npm run delete-database # wipe all explorer data
|
|
|
|
# CSS compilation (SASS → CSS in public/css/)
|
|
node scripts/compile_css.js
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Request Flow
|
|
|
|
```
|
|
HTTP request
|
|
→ app.js (middleware: CORS, rate limiting, auth, TLS redirect)
|
|
→ routes/index.js (all web & API routes)
|
|
→ lib/database.js (Mongoose queries against models/)
|
|
→ lib/explorer.js (data transformation utilities)
|
|
→ views/*.pug (rendered response)
|
|
```
|
|
|
|
For live wallet data, routes call `lib/nodeapi.js` which wraps `lib/jsonrpc.js` for RPC calls.
|
|
|
|
### Sync Flow
|
|
|
|
```
|
|
npm run sync-blocks
|
|
→ scripts/sync.js (orchestrator, uses worker threads)
|
|
→ lib/block_sync.js (parallel block fetching & processing)
|
|
→ lib/database.js (bulk writes to MongoDB)
|
|
```
|
|
|
|
Block sync is multi-threaded (configurable parallelism). It has elastic stack-size handling for overflow errors. **The web server and sync scripts are separate processes** — sync is triggered via cron, not by the web server.
|
|
|
|
### Key Files
|
|
|
|
| File | Purpose |
|
|
|---|---|
|
|
| `app.js` | Express setup: plugin loader, CORS, ACL builder, TLS redirect |
|
|
| `lib/settings.js` | Parses and validates `settings.json`; all config access goes through here |
|
|
| `lib/database.js` | All MongoDB queries; wraps Mongoose models |
|
|
| `lib/explorer.js` | Pure utility functions for formatting block/tx/address data |
|
|
| `lib/block_sync.js` | Multi-threaded block synchronization engine |
|
|
| `lib/nodeapi.js` | Wallet RPC wrapper |
|
|
| `routes/index.js` | All Express routes (web pages + REST API) |
|
|
| `scripts/sync.js` | Entry point for `npm run sync-*` commands |
|
|
| `models/` | 12 Mongoose schemas: `tx`, `address`, `addresstx`, `stats`, `richlist`, `masternode`, `peers`, `markets`, `orphans`, `heavy`, `networkhistory`, `claimaddress` |
|
|
| `lib/markets/` | Per-exchange integrations (altmarkets, dextrade, dexomy, freiexchange, nonkyc, poloniex, xeggex, yobit) |
|
|
|
|
### Configuration
|
|
|
|
`settings.json` (gitignored, based on `settings.json.template`) controls everything: DB credentials, wallet RPC, port, TLS, themes, enabled pages, market exchanges, API access. Read through `lib/settings.js` to understand available options and their defaults.
|
|
|
|
### Plugin System
|
|
|
|
Early-stage plugin system. Plugins are loaded in `app.js` from the `plugins/` directory. Currently a placeholder only.
|
|
|
|
### Testing
|
|
|
|
Tests are in `test/` using Jasmine:
|
|
- `explorerSpec.js` — tests for `lib/explorer.js` utilities
|
|
- `marketSpec.js` — tests for market helper functions
|
|
- `testData.js` — shared fixtures
|
|
|
|
There is no linting configured. No TypeScript.
|