archy/GETTING_STARTED.md

# 🚀 Archipelago - Getting Started

Welcome to Archipelago! This guide will get you up and running in minutes.

## ⚡ Quick Start

### Step 1: Install Dependencies

Run the automated installation script:

```bash
./INSTALL.sh
```

This installs everything you need:
- ✅ Rust (latest stable)
- ✅ Node.js 18+
- ✅ Podman (container runtime)
- ✅ PostgreSQL 15
- ✅ All project dependencies

**Note:** The script requires administrator privileges for Homebrew and system tools.

### Step 2: Verify Installation

```bash
./verify-install.sh
```

This checks that all dependencies are properly installed and configured.

### Step 3: Configure (Optional)

Copy environment files and adjust if needed:

```bash
# Backend configuration
cp core/.env.example core/.env

# Frontend configuration
cp neode-ui/.env.example neode-ui/.env
```

### Step 4: Start Development

Open two terminal windows:

**Terminal 1 - Backend:**
```bash
cd core
cargo run --bin archipelago
```

**Terminal 2 - Frontend:**
```bash
cd neode-ui
npm run dev
```

### Step 5: Open in Browser

Navigate to: **http://localhost:8100**

---

## 📋 What Gets Installed

| Tool | Purpose | Version Required |
|------|---------|-----------------|
| **Rust** | Backend development | Latest stable (1.93+) |
| **Node.js** | Frontend & custom apps | v18 or higher |
| **Podman** | Container runtime | Latest |
| **PostgreSQL** | Database | v15 |
| **Homebrew** | Package manager (macOS) | Latest |

---

## 🎯 Alternative: Manual Installation

If you prefer to install manually or the script fails, follow these steps:

### 1. Install Homebrew (if not installed)

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

### 2. Install Rust

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
```

### 3. Install Node.js, Podman, and PostgreSQL

```bash
brew install node podman postgresql@15
```

### 4. Initialize Podman

```bash
podman machine init
podman machine start
```

### 5. Start PostgreSQL

```bash
brew services start postgresql@15
createdb archipelago_dev
```

### 6. Install Project Dependencies

```bash
# Frontend
cd neode-ui
npm install

# Custom apps
cd ../apps/did-wallet && npm install
cd ../endurain && npm install
cd ../morphos-server && npm install
cd ../router && npm install
cd ../web5-dwn && npm install

# Backend (this may take a while)
cd ../../core
cargo build
```

---

## 🔍 Verify Everything Works

Run the verification script:

```bash
./verify-install.sh
```

You should see all checkmarks (✓). If you see warnings (⚠) or errors (✗), follow the suggested commands to fix them.

---

## 🏃 Development Modes

### Mode 1: Full Stack (Recommended)

Best for full-stack development with real backend API.

**Terminal 1:**
```bash
cd core && cargo run --bin archipelago
```

**Terminal 2:**
```bash
cd neode-ui && npm run dev
```

**URLs:**
- Frontend: http://localhost:8100
- Backend: http://localhost:5959

### Mode 2: Mock Backend (Fastest)

Best for frontend-only development without backend setup.

**Single Terminal:**
```bash
cd neode-ui && npm run dev:mock
```

**URL:**
- Frontend: http://localhost:8100
- Mock API: http://localhost:3000

### Mode 3: Quick Dev Script

Uses convenience scripts for easy startup.

```bash
./scripts/dev.sh          # Mock backend mode
# or
./scripts/dev-start.sh    # Interactive mode
```

---

## 📁 Project Structure

```
archy/
├── 📄 INSTALL.sh                # Install all dependencies
├── 📄 verify-install.sh         # Verify installation
├── 📄 SETUP_GUIDE.md            # Detailed setup guide
├── 📄 QUICK_REFERENCE.md        # Command reference
├── 📄 README.md                 # Main documentation
│
├── 🦀 core/                     # Rust backend
│   ├── archipelago/            # Main binary
│   ├── container/              # Container management
│   ├── parmanode/              # Parmanode integration
│   ├── security/               # Security modules
│   └── performance/            # Performance optimization
│
├── 🎨 neode-ui/                 # Vue.js frontend
│   ├── src/                    # Source files
│   ├── public/                 # Static assets
│   └── package.json            # Node dependencies
│
├── 📦 apps/                     # Containerized apps
│   ├── bitcoin-core/           # Bitcoin node
│   ├── lnd/                    # Lightning Network
│   ├── router/                 # Mesh router
│   ├── did-wallet/             # Web5 wallet
│   └── web5-dwn/               # Web5 DWN server
│
├── 📚 docs/                     # Documentation
│   ├── development-setup.md
│   ├── architecture.md
│   └── app-manifest-spec.md
│
└── 🔧 scripts/                  # Development scripts
    ├── dev.sh
    └── dev-start.sh
```

---

## 🛠️ Common Commands

### Development

```bash
# Start backend
cd core && cargo run --bin archipelago

# Start frontend
cd neode-ui && npm run dev

# Start with mock backend
cd neode-ui && npm run dev:mock

# Build for production
cd neode-ui && npm run build
cd core && cargo build --release
```

### Container Apps

```bash
# Build all apps
cd apps && ./build.sh

# Build specific app
cd apps && ./build.sh router
```

### Maintenance

```bash
# Update Rust
rustup update

# Update Node packages
cd neode-ui && npm update

# Check PostgreSQL status
brew services list | grep postgresql

# Check Podman status
podman machine list
```

---

## 🐛 Troubleshooting

### Port Already in Use

```bash
# Find what's using the port
lsof -i :5959   # Backend
lsof -i :8100   # Frontend

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

### Podman Not Running

```bash
podman machine start
```

### PostgreSQL Not Running

```bash
brew services start postgresql@15
```

### Rust Compilation Errors

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

### Node Module Issues

```bash
cd neode-ui
rm -rf node_modules package-lock.json
npm install
```

---

## 📖 Next Steps

Once everything is running:

1. **Explore the UI** at http://localhost:8100
2. **Read the docs:**
   - [SETUP_GUIDE.md](SETUP_GUIDE.md) - Detailed setup
   - [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Command cheatsheet
   - [docs/architecture.md](docs/architecture.md) - System architecture
   - [apps/QUICKSTART.md](apps/QUICKSTART.md) - Build and run apps

3. **Build containerized apps:**
   ```bash
   cd apps
   ./build.sh
   ```

4. **Install apps via UI** at http://localhost:8100

---

## 💡 Tips

- Use `cargo watch` for auto-reload:
  ```bash
  cargo install cargo-watch
  cd core && cargo watch -x 'run --bin archipelago'
  ```

- Frontend has hot module replacement (HMR) - changes reflect instantly

- Keep PostgreSQL and Podman running in the background

- Use the mock backend for quick UI prototyping

---

## 🆘 Getting Help

1. Run `./verify-install.sh` to diagnose issues
2. Check the [SETUP_GUIDE.md](SETUP_GUIDE.md) for detailed instructions
3. Review [docs/](docs/) for specific topics
4. Make sure all services are running (PostgreSQL, Podman)

---

## ✅ Success Checklist

- [ ] Rust installed (`rustc --version`)
- [ ] Node.js installed (`node --version`)
- [ ] Podman installed and running (`podman machine list`)
- [ ] PostgreSQL running (`brew services list`)
- [ ] Frontend dependencies installed (`neode-ui/node_modules` exists)
- [ ] Backend compiles (`cd core && cargo build`)
- [ ] Can access frontend at http://localhost:8100
- [ ] Can access backend at http://localhost:5959

---

**Welcome to Archipelago! Happy coding! 🎉**