Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
parent aafcd913c2
commit 88bc76da91
815 changed files with 125522 additions and 264 deletions
--- a/docs/DATABASE_CONNECTION_GUIDE.md
+++ b/docs/DATABASE_CONNECTION_GUIDE.md
@@ -0,0 +1,171 @@
+# Database Connection Guide
+
+## Important: Two Different Database Users
+
+There are **two separate database systems**:
+
+1. **Blockscout Database** (for Blockscout explorer)
+   - User: `blockscout`
+   - Password: `blockscout`
+   - Database: `blockscout`
+
+2. **Custom Explorer Backend Database** (for tiered architecture)
+   - User: `explorer`
+   - Password: `***REDACTED-LEGACY-PW***`
+   - Database: `explorer`
+
+## Correct Connection Command
+
+For the **custom explorer backend** (tiered architecture), use:
+
+```bash
+PGPASSWORD='***REDACTED-LEGACY-PW***' psql -h localhost -U explorer -d explorer -c "SELECT 1;"
+```
+
+**NOT:**
+```bash
+# ❌ Wrong - this is for Blockscout
+PGPASSWORD='blockscout' psql -h localhost -U blockscout -d explorer -c "SELECT 1;"
+```
+
+## Step-by-Step Database Setup
+
+### 1. Test Connection
+
+```bash
+# Test connection to custom explorer database
+PGPASSWORD='***REDACTED-LEGACY-PW***' psql -h localhost -U explorer -d explorer -c "SELECT version();"
+```
+
+### 2. Check if Tables Exist
+
+```bash
+# Check for track schema tables
+PGPASSWORD='***REDACTED-LEGACY-PW***' psql -h localhost -U explorer -d explorer -c "
+SELECT table_name 
+FROM information_schema.tables 
+WHERE table_schema = 'public' 
+AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transfers')
+ORDER BY table_name;
+"
+```
+
+### 3. Run Migration (if tables don't exist)
+
+```bash
+cd explorer-monorepo
+PGPASSWORD='***REDACTED-LEGACY-PW***' psql -h localhost -U explorer -d explorer \
+  -f backend/database/migrations/0010_track_schema.up.sql
+```
+
+### 4. Verify Migration
+
+```bash
+# Should return 4 or more
+PGPASSWORD='***REDACTED-LEGACY-PW***' psql -h localhost -U explorer -d explorer -c "
+SELECT COUNT(*) as table_count 
+FROM information_schema.tables 
+WHERE table_schema = 'public' 
+AND table_name IN ('wallet_nonces', 'operator_roles', 'addresses', 'token_transfers', 'analytics_flows', 'operator_events');
+"
+```
+
+## Troubleshooting
+
+### If Connection Fails
+
+1. **Check if PostgreSQL is running:**
+   ```bash
+   systemctl status postgresql
+   ```
+
+2. **Check if user exists:**
+   ```bash
+   # Connect as postgres superuser
+   sudo -u postgres psql -c "\du"
+   ```
+   
+   You should see both `blockscout` and `explorer` users.
+
+3. **Check if database exists:**
+   ```bash
+   sudo -u postgres psql -c "\l"
+   ```
+   
+   You should see both `blockscout` and `explorer` databases.
+
+4. **Create user and database if missing:**
+   ```bash
+   sudo -u postgres psql << EOF
+   CREATE USER explorer WITH PASSWORD '***REDACTED-LEGACY-PW***';
+   CREATE DATABASE explorer OWNER explorer;
+   GRANT ALL PRIVILEGES ON DATABASE explorer TO explorer;
+   \q
+   EOF
+   ```
+
+### If Password Authentication Fails
+
+1. **Verify password is correct:**
+   - Custom explorer: `***REDACTED-LEGACY-PW***`
+   - Blockscout: `blockscout`
+
+2. **Check pg_hba.conf:**
+   ```bash
+   sudo cat /etc/postgresql/*/main/pg_hba.conf | grep -E "(local|host.*explorer)"
+   ```
+   
+   Should allow password authentication for local connections.
+
+3. **Reload PostgreSQL:**
+   ```bash
+   sudo systemctl reload postgresql
+   ```
+
+## Quick Fix Script
+
+Use the provided script:
+
+```bash
+cd explorer-monorepo
+export DB_PASSWORD='***REDACTED-LEGACY-PW***'
+bash scripts/fix-database-connection.sh
+```
+
+This script will:
+- Test the connection
+- Check for existing tables
+- Run migration if needed
+- Provide next steps
+
+## After Database is Connected
+
+1. **Restart API server with database:**
+   ```bash
+   pkill -f api-server
+   cd explorer-monorepo/backend
+   export DB_PASSWORD='***REDACTED-LEGACY-PW***'
+   export JWT_SECRET='your-secret-here'
+   ./bin/api-server
+   ```
+
+2. **Verify health endpoint:**
+   ```bash
+   curl http://localhost:8080/health
+   ```
+   
+   Should show database as "ok" instead of "error".
+
+3. **Test authentication:**
+   ```bash
+   curl -X POST http://localhost:8080/api/v1/auth/nonce \
+     -H 'Content-Type: application/json' \
+     -d '{"address":"0x1234567890123456789012345678901234567890"}'
+   ```
+
+## Summary
+
+- **Custom Explorer Backend:** Use `explorer` user with password `***REDACTED-LEGACY-PW***`
+- **Blockscout:** Use `blockscout` user with password `blockscout`
+- **They are separate systems** with separate databases
+