archy/QUICK_REFERENCE.md

Archipelago Quick Reference

Installation

# Install all dependencies
./INSTALL.sh

# Verify installation
./verify-install.sh

Development

Start Development Servers

# Quick start (mock backend)
./scripts/dev.sh

# Interactive start
./scripts/dev-start.sh

# Manual start
# Terminal 1:
cd core && cargo run --bin archipelago

# Terminal 2:
cd neode-ui && npm run dev

URLs

• Frontend: http://localhost:8100
• Backend API: http://localhost:5959
• Backend RPC: http://localhost:5959/rpc/v1

Common Commands

Rust Backend

cd core

# Run in development mode
cargo run --bin archipelago

# Run in release mode (faster)
cargo run --bin archipelago --release

# Build only
cargo build

# Run tests
cargo test

# Auto-reload on changes
cargo install cargo-watch
cargo watch -x 'run --bin archipelago'

# Check for errors without building
cargo check

Frontend (Vue.js)

cd neode-ui

# Install dependencies
npm install

# Development server
npm run dev

# With mock backend
npm run dev:mock

# Build for production
npm run build

# Type checking
npm run type-check

# Preview production build
npm run preview

Apps (Containerized)

cd apps

# Build all apps
./build.sh

# Build specific app
./build.sh router
./build.sh bitcoin-core
./build.sh did-wallet

# Install app dependencies (for custom apps)
cd apps/router && npm install
cd apps/did-wallet && npm install
cd apps/web5-dwn && npm install

Container Management (Podman)

# Check Podman status
podman --version
podman info

# Manage Podman machine
podman machine list
podman machine start
podman machine stop
podman machine ssh

# List containers
podman ps
podman ps -a

# List images
podman images

# Remove all stopped containers
podman container prune

# Remove unused images
podman image prune

Database (PostgreSQL)

# Start/stop PostgreSQL service
brew services start postgresql@15
brew services stop postgresql@15
brew services restart postgresql@15

# Check service status
brew services list | grep postgresql

# Create database
createdb archipelago_dev

# Drop database
dropdb archipelago_dev

# Connect to database
psql archipelago_dev

# List databases
psql -l

Configuration

Backend Configuration

File: core/.env

DATADIR=/tmp/archipelago-dev
RPC_BIND=127.0.0.1:5959
LOG_LEVEL=debug
DATABASE_URL=postgresql://localhost/archipelago_dev
ARCHIPELAGO_DEV_MODE=true

Frontend Configuration

File: neode-ui/.env

VITE_BACKEND_URL=http://localhost:5959
VITE_API_BASE=/rpc/v1
VITE_DEV_MODE=true

Troubleshooting

Ports Already in Use

# Find process using port
lsof -i :5959
lsof -i :8100

# Kill process
kill -9 <PID>

PostgreSQL Issues

# Check if running
pg_isready

# View logs
tail -f /opt/homebrew/var/log/postgresql@15.log

# Restart service
brew services restart postgresql@15

Podman Issues

# Restart machine
podman machine stop
podman machine start

# Reset machine (WARNING: destroys all containers/images)
podman machine rm
podman machine init
podman machine start

Rust Compilation Issues

# Update Rust
rustup update

# Clean and rebuild
cd core
cargo clean
cargo build

Node/NPM Issues

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm cache clean --force
npm install

Project Structure

archy/
├── INSTALL.sh              # Installation script
├── verify-install.sh       # Verify installation
├── SETUP_GUIDE.md          # Detailed setup guide
├── README.md               # Main documentation
├── core/                   # Rust backend
│   ├── .env               # Backend config (create from .env.example)
│   ├── archipelago/       # Main binary
│   ├── container/         # Container management
│   ├── parmanode/         # Parmanode integration
│   ├── security/          # Security modules
│   └── performance/       # Performance optimization
├── neode-ui/              # Vue.js frontend
│   ├── .env              # Frontend config (create from .env.example)
│   └── src/              # Source files
├── apps/                  # Containerized applications
│   ├── build.sh          # Build apps
│   ├── bitcoin-core/     # Bitcoin node
│   ├── router/           # Custom router app
│   ├── did-wallet/       # Web5 DID wallet
│   └── web5-dwn/         # Web5 DWN server
├── docs/                  # Documentation
├── scripts/               # Development scripts
└── image-recipe/          # OS image build files

Useful Aliases

Add to your ~/.zshrc or ~/.bashrc:

# Archipelago aliases
alias archy-backend='cd ~/Projects/archy/core && cargo run --bin archipelago'
alias archy-frontend='cd ~/Projects/archy/neode-ui && npm run dev'
alias archy-verify='cd ~/Projects/archy && ./verify-install.sh'
alias archy-apps='cd ~/Projects/archy/apps'
alias archy-docs='cd ~/Projects/archy/docs'

Development Workflow

1. Start backend (Terminal 1)

   cd core && cargo run --bin archipelago
   

2. Start frontend (Terminal 2)

   cd neode-ui && npm run dev
   

3. Make changes to code

4. See changes live:

   • Frontend: Auto-reloads with Vite HMR
   • Backend: Restart cargo or use cargo-watch

5. Build apps when needed:

   cd apps && ./build.sh <app-name>
   

Resources

• Development Setup Guide
• Architecture Documentation
• App Manifest Specification
• Apps Quick Start
• Apps Development Guide

Getting Help

1. Check SETUP_GUIDE.md for detailed instructions
2. Run ./verify-install.sh to diagnose issues
3. Review error messages carefully
4. Check service status (PostgreSQL, Podman)
5. Look in docs/ for specific topics