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