Day-1 Onboarding

Everything a new engineer needs to do on day 1 to be productive in the VelaPay workspace. By the end of this guide you will have:

• The full toolchain (Bun, Anchor, Solana CLI, wrangler) installed.
• The 15-repo workspace cloned and dependencies installed.
• A working devnet keypair.
• The protocol building and the LiteSVM test suite passing.
• The merchant dashboard running locally.
• The hosted checkout, subscriber portal, and admin dashboard running locally.
• A clear sense of where to look next.

This page is the cross-repo equivalent of each repo's README — it is the runbook for getting from "git clone" to "I can ship code".

Prerequisites

Tool	Version	Why
Bun	1.3.x	Workspace package manager + runtime + test runner
Rust	1.89.0+	Anchor 0.32 requires it for stable IDL building
Solana CLI (Agave)	2.3.0+ stable	Validator, deploy, keygen
Anchor CLI	0.32.1 (exact)	Program build + IDL
Node.js	18+	Some tooling assumes a Node-compatible runtime
Git	latest	Workspace clone + branch ops
wrangler	4.78.x	Cloudflare deploy (auto-installed via bunx)

Install order (macOS reference)

# Bun
curl -fsSL https://bun.sh/install | bash

# Rust + Solana via Anchor's recommended path
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
sh -c "$(curl -sSfL https://release.anza.xyz/v2.3.0/install)"   # agave-install
cargo install --git https://github.com/solana-foundation/anchor avm --force
avm install 0.32.1 && avm use 0.32.1

Verify:

bun --version           # 1.3.x
rustc --version         # 1.89.0+
solana --version        # 2.3.x
anchor --version        # anchor-cli 0.32.1

Workspace Clone

The workspace is 15 repos under a single parent directory. Bun's file: workspace links require all repos to live as siblings.

mkdir -p ~/Developments/vela-labs && cd ~/Developments/vela-labs

# Product repos (9)
for r in vela-protocol vela-sdk vela-dashboard vela-admin vela-portal \
         vela-checkout vela-widget vela-web vela-docs; do
  git clone "https://github.com/laitsky/$r"
done

# Support repos (6)
for r in vela-brand vela-webhook vela-mail vela-mail-smoke vela-synthetic vela-demo; do
  git clone "https://github.com/laitsky/$r"
done

Resulting tree:

vela-labs/
├── vela-protocol/      ├── vela-portal/      ├── vela-mail-smoke/
├── vela-sdk/           ├── vela-checkout/    ├── vela-synthetic/
├── vela-dashboard/     ├── vela-widget/      ├── vela-demo/
├── vela-admin/         ├── vela-web/         ├── internal-wiki/
├── vela-brand/         ├── vela-docs/        └── .planning/
├── vela-webhook/       ├── vela-mail/

Install dependencies repo-by-repo (Bun is fast — this is parallelizable):

for r in vela-*; do (cd "$r" && bun install) ; done

Solana Keypair

Generate (or import) a devnet keypair and fund it:

solana-keygen new --outfile ~/.config/solana/id.json
solana config set --url https://api.devnet.solana.com
solana airdrop 5
solana balance

For protocol upgrades, you also need program keypairs. They live under ~/.config/velapay/keys/devnet/ — see Environment Registry → Solana Environments. New engineers do not need program keypairs for app development; only deploy operators do.

Build the Protocol

cd vela-protocol
anchor build                       # ~2 minutes first build
bun run program-ids:check          # confirms IDs match Anchor.toml

Sanity-check by running the LiteSVM test suite (orders of magnitude faster than solana-test-validator):

cargo test                         # Rust unit tests (LiteSVM crate)
bun test                           # TS integration tests (anchor-litesvm + bun:test)

If both pass, the protocol is healthy on your machine.

Run the SDK

The SDK auto-builds when consumed via file: link, but it's useful to run its tests directly:

cd ../vela-sdk
bun install
bun test
bunx vela --help                   # CLI smoke

Run the Dashboard

The dashboard is dual-runtime — a Bun server + a Cloudflare Worker.

cd ../vela-dashboard
bun install

# Frontend + Bun-runtime backend
bun run dev                        # vite dev (HMR)

# In another shell — Cloudflare Worker (D1, Queues, R2 bindings)
bun run cf:dev                     # wrangler dev

Open the URL Vite prints. You should see the merchant dashboard. Magic-link auth uses a local Mailpit instance — see .env.example.

Run Other Surfaces

Each surface has a dev script. Most just need bun install && bun run dev:

Surface	Command	What you'll see
Subscriber portal	cd vela-portal && bun run dev	portal.velapay.com mock
Hosted checkout	cd vela-checkout && bun run dev	pay.velapay.com mock
Admin console	cd vela-admin && bun run dev	Internal protocol ops
Widget	cd vela-widget && bun run dev	Embeddable iframe checkout
Landing page	cd vela-web && bun run dev	velapay.com (Astro)
Docs	cd vela-docs && bun run dev	docs.velapay.com (Starlight)
Internal wiki	cd internal-wiki && bun run dev	This site (VitePress)
Demo	cd vela-demo && bun run dev	End-to-end devnet demo

What to Read Next

In rough order:

1. Workspace Map → — orientation across all 15 repos and the planning layer.
2. Architecture → — 4-layer system overview, dual-program protocol, Arcium integration.
3. Glossary → — vocabulary you'll see all over the codebase (mandate, plan, credential, pull, stream, hook, MXE).
4. Operations Handbook → — source-of-truth hierarchy and daily operating principles.
5. Repo Contracts → — which repo to change for a given task.
6. Verification Matrix → — commands that prove your local stack is integrated.
7. Testing Strategy → — when to write LiteSVM unit, anchor-litesvm integration, Playwright E2E, or synthetic-monitor coverage.
8. Code Review Checklist → — the bar for shipping a PR.

Common Day-1 Friction

Symptom	Likely cause	Fix
anchor build fails on solana-invoke	Solana CLI < 2.3.0	Reinstall via agave-install init 2.3.0
bun install reports peer mismatch	Sibling repo missing	Make sure all 15 repos are cloned as siblings
Dashboard auth fails with magic-link	Mailpit not running	docker compose up -d mailpit (see dashboard README)
Wrangler can't find D1	Run bunx wrangler d1 create vela-dashboard-dev first	One-time per local environment
solana airdrop rate-limited	Devnet faucet is bursty	Use https://faucet.solana.com from a browser, or wait
anchor test is slow	Falling back to solana-test-validator	Prefer cargo test (LiteSVM) for unit-level work

Help

• .planning/STATE.md — current execution state.
• internal-wiki/operations/ — operational runbooks.
• vela-docs/ — public-facing developer documentation.
• Operating principles: Operations Handbook →.