# Development Setup Guide

This guide explains how to run Archipelago locally for development.

## Prerequisites

- **Rust** (latest stable) - [Install Rust](https://rustup.rs/)
- **Node.js** (v18+) and **npm** - [Install Node.js](https://nodejs.org/)
- **Podman** (for container features) - [Install Podman](https://podman.io/getting-started/installation)
- **PostgreSQL** (for backend database) - [Install PostgreSQL](https://www.postgresql.org/download/)

## Project Structure

The project has two main components:

1. **Backend** (`core/startos/`) - Rust backend with RPC API
2. **Frontend** (`neode-ui/`) - Vue.js 3 frontend

## Quick Start

### Option 1: Mock Backend (Fastest for UI Development)

For frontend-only development, use the mock backend:

```bash
cd neode-ui
npm install
npm run dev:mock
```

This starts:
- Mock backend server on port 3000
- Vite dev server on port 8100
- Open http://localhost:8100

### Option 2: Full Stack Development

For full-stack development with the real backend:

#### Terminal 1: Backend

```bash
cd core
cargo run --bin startbox --features cli,daemon
```

The backend will:
- Start RPC server on port 5959
- Initialize database if needed
- Serve API endpoints

#### Terminal 2: Frontend

```bash
cd neode-ui
npm install
npm run dev:real
```

Or just:
```bash
npm run dev
```

The frontend will:
- Start Vite dev server on port 8100
- Proxy API requests to backend on port 5959
- Open http://localhost:8100

## Development Scripts

### Frontend Scripts (`neode-ui/package.json`)

- `npm run dev` - Start Vite dev server
- `npm run dev:mock` - Start with mock backend
- `npm run dev:real` - Start with real backend (backend must be running separately)
- `npm run build` - Build for production
- `npm run type-check` - TypeScript type checking

### Backend Scripts

- `cargo run --bin startbox` - Run backend in dev mode
- `cargo run --bin startbox --release` - Run backend in release mode
- `cargo test` - Run tests
- `cargo build` - Build backend

## Environment Variables

### Backend

Create `.env` in `core/` directory:

```bash
DATADIR=/tmp/archipelago-dev
RPC_BIND=127.0.0.1:5959
LOG_LEVEL=debug
```

### Frontend

Create `.env` in `neode-ui/` directory:

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

## Database Setup

The backend uses PostgreSQL. For development:

```bash
# Create database
createdb archipelago_dev

# Or use Docker
docker run -d \
  --name archipelago-postgres \
  -e POSTGRES_PASSWORD=dev \
  -e POSTGRES_DB=archipelago_dev \
  -p 5432:5432 \
  postgres:15
```

## Container Development

To test container features locally, you need Podman:

```bash
# Install Podman (macOS)
brew install podman

# Initialize Podman machine
podman machine init
podman machine start

# Verify
podman --version
```

## Hot Reload

- **Frontend**: Vite provides instant hot module replacement (HMR)
- **Backend**: Use `cargo watch` for auto-reload:

```bash
cargo install cargo-watch
cargo watch -x 'run --bin startbox'
```

## Debugging

### Frontend

- Use browser DevTools
- Vue DevTools extension recommended
- Console logs available

### Backend

- Use `RUST_LOG=debug` environment variable
- Add `println!` or use `tracing` macros
- Use a debugger like `lldb` or `gdb`

## Common Issues

### Port Already in Use

If port 5959 or 8100 is already in use:

```bash
# Backend - change port in .env
RPC_BIND=127.0.0.1:5958

# Frontend - change in vite.config.ts
server: { port: 8101 }
```

### Database Connection Errors

- Ensure PostgreSQL is running
- Check connection string in backend config
- Verify database exists

### Container Features Not Working

- Ensure Podman is installed and running
- Check Podman machine is started (macOS)
- Verify rootless Podman is configured

## Testing

### Frontend Tests

```bash
cd neode-ui
npm test
```

### Backend Tests

```bash
cd core
cargo test
```

## Building for Production

### Frontend

```bash
cd neode-ui
npm run build
```

Output: `dist/` directory

### Backend

```bash
cd core
cargo build --release
```

Output: `target/release/startbox`

## Next Steps

- Read [Architecture Documentation](./architecture.md)
- Check [App Manifest Specification](./app-manifest-spec.md)
- Review [Coding Standards](../CODING_STANDARDS.md)