# Archipelago Quick Reference

## Installation

```bash
# Install all dependencies
./INSTALL.sh

# Verify installation
./verify-install.sh
```

## Development

### Start Development Servers

```bash
# 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

```bash
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)

```bash
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)

```bash
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)

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

```bash
# 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`

```bash
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`

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

## Troubleshooting

### Ports Already in Use

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

# Kill process
kill -9 <PID>
```

### PostgreSQL Issues

```bash
# 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

```bash
# 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

```bash
# Update Rust
rustup update

# Clean and rebuild
cd core
cargo clean
cargo build
```

### Node/NPM Issues

```bash
# 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`:

```bash
# 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)
   ```bash
   cd core && cargo run --bin archipelago
   ```

2. **Start frontend** (Terminal 2)
   ```bash
   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:
   ```bash
   cd apps && ./build.sh <app-name>
   ```

## Resources

- [Development Setup Guide](docs/development-setup.md)
- [Architecture Documentation](docs/architecture.md)
- [App Manifest Specification](docs/app-manifest-spec.md)
- [Apps Quick Start](apps/QUICKSTART.md)
- [Apps Development Guide](apps/DEVELOPMENT.md)

## Getting Help

1. Check [SETUP_GUIDE.md](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