From 7b33fbc104757f6167727d6a01f772ca49f3d9c6 Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Thu, 24 Sep 2026 15:37:21 -0400 Subject: [PATCH 1/8] docs: add developer onboarding guide to CONTRIBUTING.md Replace the scaffold placeholder with setup instructions for frontend, backend, and contracts, plus architecture overview, code standards, testing guide, and PR process. Closes #561 --- CONTRIBUTING.md | 260 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 258 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e015aa7..fc8caa74 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,259 @@ -# Contributing +# Contributing to PayD -This is a guide to contributing to `scaffold-stellar-frontend` itself. Feel free to delete or modify it for your own project. +Thanks for helping improve PayD — a Stellar-based cross-border payroll platform. +This guide covers local setup, architecture, coding standards, testing, and the +pull request process. + +## Table of contents + +1. [Code of conduct](#code-of-conduct) +2. [Architecture overview](#architecture-overview) +3. [Prerequisites](#prerequisites) +4. [Local development setup](#local-development-setup) +5. [Code style and standards](#code-style-and-standards) +6. [Testing guide](#testing-guide) +7. [Pull request process](#pull-request-process) +8. [Where to get help](#where-to-get-help) + +## Code of conduct + +By participating, you agree to follow the [Code of Conduct](./CODE_OF_CONDUCT.md). +Be respectful, assume good intent, and keep discussions focused on the work. + +## Architecture overview + +PayD has three main layers that work together: + +``` +┌────────────────────┐ HTTPS/JSON ┌────────────────────┐ +│ Frontend (React) │◄───────────────────►│ Backend (Express) │ +│ Vite + TypeScript │ │ Node.js + PG/Redis│ +└─────────┬──────────┘ └─────────┬──────────┘ + │ Stellar Wallets Kit │ Stellar SDK / Soroban RPC + ▼ ▼ +┌─────────────────────────────────────────────────────────────────┐ +│ Stellar Network │ +│ Horizon · Soroban RPC · Anchors (cash-out) · Org assets │ +└─────────────────────────────────────────────────────────────────┘ + ▲ + │ Rust / Soroban +┌─────────┴──────────┐ +│ Contracts (Rust) │ bulk_payment · vesting_escrow · revenue_split · … +└────────────────────┘ +``` + +| Layer | Role | +| ----- | ---- | +| **Frontend** (`frontend/`, root Vite app) | Employer dashboard, employee portal, wallet connect | +| **Backend** (`backend/`) | Auth, payroll, employees, schedules, audits, webhooks | +| **Contracts** (`contracts/`) | Soroban programs for payments, vesting, splits | +| **Infra** | PostgreSQL for persistence, Redis for cache/rate limits | + +High-level request flow: + +1. Employer or employee authenticates (wallet / OAuth / 2FA where required). +2. Frontend calls `/api/...` on the Express backend. +3. Backend validates input, enforces tenant isolation and rate limits, then + reads/writes Postgres and/or submits Stellar transactions. +4. Contract events and payment results are indexed for audit and dashboards. + +## Prerequisites + +Install these before cloning: + +| Tool | Notes | +| ---- | ----- | +| **Node.js** 22+ | Frontend and backend | +| **npm** (or yarn/pnpm) | Package management | +| **Docker** (optional) | Local Postgres / Redis | +| **Rust** + **Stellar CLI** | Only needed for contract work | +| **Git** | Branching and PRs | + +## Local development setup + +### 1. Clone and install + +```bash +git clone https://github.com/Protocol-Guild/PayD.git +cd PayD +``` + +Install root/frontend dependencies: + +```bash +npm install +``` + +Install backend dependencies: + +```bash +cd backend +npm install +cd .. +``` + +### 2. Environment configuration + +Copy the example env files and edit secrets for your machine: + +```bash +cp .env.example .env +cp backend/.env.example backend/.env +``` + +Important backend variables (see `backend/.env.example`): + +- `PORT` — API port (default `3001`) +- `DATABASE_URL` / `DB_*` — Postgres connection +- `STELLAR_HORIZON_URL` / `STELLAR_NETWORK_PASSPHRASE` — network target +- `SDS_*` — optional Stellar Data Service settings +- `NODE_ENV` — `development` for verbose errors; never leak stacks in production + +Frontend public vars are prefixed with `PUBLIC_STELLAR_*` in `.env.example`. + +### 3. Database + +Using Docker: + +```bash +docker run --name payd-postgres \ + -e POSTGRES_PASSWORD=mypassword \ + -e POSTGRES_DB=payd_db \ + -p 5432:5432 -d postgres:15 +``` + +Then run migrations from `backend/`: + +```bash +cd backend +npm run db:migrate +npm run db:verify-schema +``` + +### 4. Run the apps + +**Backend** (API on port 3001 by default): + +```bash +cd backend +npm run dev +``` + +**Frontend** (Vite): + +```bash +# from repo root +npm run dev +# or +cd frontend && npm run dev +``` + +**Contracts** (optional): + +```bash +# build workspace crates +cargo build --release +# or use Stellar CLI / scaffold workflows as documented in contract READMEs +``` + +Health check: `GET http://localhost:3001/health` + +## Code style and standards + +- **Language**: TypeScript for frontend and backend; Rust for Soroban contracts. +- **Formatting**: Prettier (root `npm run format`). Do not hand-fight style. +- **Linting**: ESLint (`npm run lint` in root/frontend; `npm run lint` in backend). +- **Modules**: Backend uses ESM (`"type": "module"`). Prefer explicit `.js` + extensions in relative TypeScript imports to match existing files. +- **Errors**: Prefer typed errors (`AppError` / subclasses in `backend/src/errors`) + and let the global error middleware format responses. Do not return raw + database or stack messages to clients outside development. +- **Security**: Never commit secrets. Sanitize logs (passwords, tokens, keys). + Preserve tenant isolation middleware on multi-tenant routes. +- **Commits**: Prefer [Conventional Commits](https://www.conventionalcommits.org/) + (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`). Reference issues with + `Closes #N` when the change fully addresses them. +- **License**: Project license is **Apache-2.0** (see `LICENSE`). Keep that + consistent in docs and badges. + +## Testing guide + +### Backend + +```bash +cd backend +npm test # all Jest unit/integration tests +npm test -- --coverage # coverage report +npm test -- --testPathPatterns=X # subset by path pattern +``` + +Tests live next to code under `backend/src/**/__tests__/**/*.test.ts`. +Mock external I/O (DB, Redis, Horizon) unless you are writing an explicit +integration test. + +Additional helpers: + +- `npm run db:migrate:dry-run` — validate migrations without applying +- `backend/test-*.sh` — manual/API smoke scripts when documented + +### Frontend + +```bash +# from frontend/ or via root scripts where available +npm run lint +npm run build +npm run test:e2e # Playwright +npm run test:e2e:ui # interactive Playwright +``` + +### Contracts + +```bash +cargo test +# follow per-crate docs under contracts// +``` + +### CI expectations + +GitHub Actions (see `.github/workflows/`) run build, e2e, contract release, and +secrets checks. A PR should pass the same checks you can run locally before +requesting review. + +## Pull request process + +1. **Find or open an issue** describing the bug/feature. Comment if you intend + to work on it so others do not duplicate effort. +2. **Branch from `main`** with a descriptive name, e.g. `fix/payroll-timeout` + or `feat/error-middleware`. +3. **Keep the diff focused**. One concern per PR. Avoid drive-by refactors + unrelated to the issue. +4. **Add or update tests** for behavioral changes. Document env vars and + migrations when you introduce them. +5. **Write a clear PR description**: + - What changed and why + - How you tested it + - Linked issue (`Closes #123`) +6. **Self-review** the diff: no secrets, no debug leftovers, consistent style. +7. **Request review**. Address feedback with follow-up commits (or a squash if + maintainers prefer). +8. **Do not force-push** to shared review branches unless a maintainer asks. + +### Review criteria + +Maintainers look for: + +- Correctness against the issue acceptance criteria +- Tests that would fail without the change +- Clear error handling and no sensitive data in responses/logs +- Readable structure matching neighboring code +- Docs updated when user-facing or contributor-facing behavior changes + +## Where to get help + +- Project overview and feature list: [README.md](./README.md) +- Backend SDS / search / multi-tenant docs: files under `backend/` +- Contract design notes: `contracts/` and related `*_ARCHITECTURE.md` docs +- Open an issue for bugs, design questions, or setup blockers + +Welcome aboard — small, well-tested contributions are preferred over large +unfocused ones. From b5455581de21d117219ab5ce8e1147e168e3f369 Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Thu, 24 Sep 2026 15:38:15 -0400 Subject: [PATCH 2/8] ci: drop invalid top-level retention-days from workflows GitHub Actions does not accept retention-days on the workflow root. That key is only valid on upload-artifact. The extra key made every workflow fail validation on push before any job started. --- .github/workflows/build.yml | 4 ---- .github/workflows/contract-release.yml | 4 ---- .github/workflows/dapp-ipfs.yml | 4 ---- .github/workflows/secrets-check.yml | 4 ---- 4 files changed, 16 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 52029992..68212ca7 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,7 +7,6 @@ on: branches: ["main"] types: [opened, synchronize, reopened, ready_for_review] -# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days env: CARGO_TERM_COLOR: always PKG_CONFIG_PATH: /usr/lib/pkgconfig @@ -113,6 +112,3 @@ jobs: - name: Run Tests working-directory: ./frontend run: npm test --if-present - -# Workflow run retention settings -retention-days: 30 \ No newline at end of file diff --git a/.github/workflows/contract-release.yml b/.github/workflows/contract-release.yml index 2655fcbc..cca80486 100644 --- a/.github/workflows/contract-release.yml +++ b/.github/workflows/contract-release.yml @@ -5,7 +5,6 @@ on: tags: - "v*" -# Retention policy: Keep successful runs for 90 days, failed/cancelled for 14 days permissions: # required permissions for the workflow id-token: write contents: write # in order to create releases @@ -27,6 +26,3 @@ jobs: package: "..." secrets: release_token: ${{ secrets.GITHUB_TOKEN }} - -# Workflow run retention settings -retention-days: 90 \ No newline at end of file diff --git a/.github/workflows/dapp-ipfs.yml b/.github/workflows/dapp-ipfs.yml index 29d16e55..5887cc7e 100644 --- a/.github/workflows/dapp-ipfs.yml +++ b/.github/workflows/dapp-ipfs.yml @@ -9,7 +9,6 @@ on: workflow_dispatch: -# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true @@ -65,6 +64,3 @@ jobs: echo "" >> $GITHUB_STEP_SUMMARY echo "- CID: ${{ steps.storacha.outputs.cid }}" >> "$GITHUB_STEP_SUMMARY" echo "- URL: ${{ steps.storacha.outputs.url }}" >> "$GITHUB_STEP_SUMMARY" - -# Workflow run retention settings -retention-days: 30 \ No newline at end of file diff --git a/.github/workflows/secrets-check.yml b/.github/workflows/secrets-check.yml index b8d3b7e8..5e989082 100644 --- a/.github/workflows/secrets-check.yml +++ b/.github/workflows/secrets-check.yml @@ -10,7 +10,6 @@ on: paths: - "k8s/**" -# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days jobs: check-secrets-placeholders: name: Verify no real secrets in k8s manifests @@ -20,6 +19,3 @@ jobs: - name: Check backend-secret.yaml for non-placeholder values run: ./scripts/check-k8s-secrets.sh - -# Workflow run retention settings -retention-days: 30 \ No newline at end of file From 8b6c4b6c8d2112a242685af934d41edbba67602f Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Thu, 24 Sep 2026 15:38:34 -0400 Subject: [PATCH 3/8] ci: drop invalid workflow-level retention-days keys GitHub Actions does not accept retention-days at the workflow root. That made build, secrets-check, contract-release, and dapp-ipfs fail with zero jobs on every push. Keep comments; set retention in repo settings. --- .github/workflows/build.yml | 1 + .github/workflows/contract-release.yml | 1 + .github/workflows/dapp-ipfs.yml | 1 + .github/workflows/secrets-check.yml | 1 + 4 files changed, 4 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 68212ca7..3241a1e7 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,6 +7,7 @@ on: branches: ["main"] types: [opened, synchronize, reopened, ready_for_review] +# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days env: CARGO_TERM_COLOR: always PKG_CONFIG_PATH: /usr/lib/pkgconfig diff --git a/.github/workflows/contract-release.yml b/.github/workflows/contract-release.yml index cca80486..344b0121 100644 --- a/.github/workflows/contract-release.yml +++ b/.github/workflows/contract-release.yml @@ -5,6 +5,7 @@ on: tags: - "v*" +# Retention policy: Keep successful runs for 90 days, failed/cancelled for 14 days permissions: # required permissions for the workflow id-token: write contents: write # in order to create releases diff --git a/.github/workflows/dapp-ipfs.yml b/.github/workflows/dapp-ipfs.yml index 5887cc7e..80b579de 100644 --- a/.github/workflows/dapp-ipfs.yml +++ b/.github/workflows/dapp-ipfs.yml @@ -9,6 +9,7 @@ on: workflow_dispatch: +# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true diff --git a/.github/workflows/secrets-check.yml b/.github/workflows/secrets-check.yml index 5e989082..447caecf 100644 --- a/.github/workflows/secrets-check.yml +++ b/.github/workflows/secrets-check.yml @@ -10,6 +10,7 @@ on: paths: - "k8s/**" +# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days jobs: check-secrets-placeholders: name: Verify no real secrets in k8s manifests From dbc55c95b0250292a9eb74abf5c28aba549fc61a Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Thu, 24 Sep 2026 15:41:30 -0400 Subject: [PATCH 4/8] ci: drop invalid top-level retention-days from workflows --- .github/workflows/build.yml | 1 - .github/workflows/contract-release.yml | 1 - .github/workflows/dapp-ipfs.yml | 1 - .github/workflows/secrets-check.yml | 1 - 4 files changed, 4 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 3241a1e7..68212ca7 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,7 +7,6 @@ on: branches: ["main"] types: [opened, synchronize, reopened, ready_for_review] -# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days env: CARGO_TERM_COLOR: always PKG_CONFIG_PATH: /usr/lib/pkgconfig diff --git a/.github/workflows/contract-release.yml b/.github/workflows/contract-release.yml index 344b0121..cca80486 100644 --- a/.github/workflows/contract-release.yml +++ b/.github/workflows/contract-release.yml @@ -5,7 +5,6 @@ on: tags: - "v*" -# Retention policy: Keep successful runs for 90 days, failed/cancelled for 14 days permissions: # required permissions for the workflow id-token: write contents: write # in order to create releases diff --git a/.github/workflows/dapp-ipfs.yml b/.github/workflows/dapp-ipfs.yml index 80b579de..5887cc7e 100644 --- a/.github/workflows/dapp-ipfs.yml +++ b/.github/workflows/dapp-ipfs.yml @@ -9,7 +9,6 @@ on: workflow_dispatch: -# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true diff --git a/.github/workflows/secrets-check.yml b/.github/workflows/secrets-check.yml index 447caecf..5e989082 100644 --- a/.github/workflows/secrets-check.yml +++ b/.github/workflows/secrets-check.yml @@ -10,7 +10,6 @@ on: paths: - "k8s/**" -# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days jobs: check-secrets-placeholders: name: Verify no real secrets in k8s manifests From 340e4910285de3e09ed4e86c24d91e6123e53f5b Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Fri, 25 Sep 2026 21:16:26 -0400 Subject: [PATCH 5/8] chore: keep this pull request scoped to its issue --- .github/workflows/build.yml | 4 ++++ .github/workflows/contract-release.yml | 4 ++++ .github/workflows/dapp-ipfs.yml | 4 ++++ .github/workflows/secrets-check.yml | 4 ++++ 4 files changed, 16 insertions(+) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 68212ca7..52029992 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -7,6 +7,7 @@ on: branches: ["main"] types: [opened, synchronize, reopened, ready_for_review] +# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days env: CARGO_TERM_COLOR: always PKG_CONFIG_PATH: /usr/lib/pkgconfig @@ -112,3 +113,6 @@ jobs: - name: Run Tests working-directory: ./frontend run: npm test --if-present + +# Workflow run retention settings +retention-days: 30 \ No newline at end of file diff --git a/.github/workflows/contract-release.yml b/.github/workflows/contract-release.yml index cca80486..2655fcbc 100644 --- a/.github/workflows/contract-release.yml +++ b/.github/workflows/contract-release.yml @@ -5,6 +5,7 @@ on: tags: - "v*" +# Retention policy: Keep successful runs for 90 days, failed/cancelled for 14 days permissions: # required permissions for the workflow id-token: write contents: write # in order to create releases @@ -26,3 +27,6 @@ jobs: package: "..." secrets: release_token: ${{ secrets.GITHUB_TOKEN }} + +# Workflow run retention settings +retention-days: 90 \ No newline at end of file diff --git a/.github/workflows/dapp-ipfs.yml b/.github/workflows/dapp-ipfs.yml index 5887cc7e..29d16e55 100644 --- a/.github/workflows/dapp-ipfs.yml +++ b/.github/workflows/dapp-ipfs.yml @@ -9,6 +9,7 @@ on: workflow_dispatch: +# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }} cancel-in-progress: true @@ -64,3 +65,6 @@ jobs: echo "" >> $GITHUB_STEP_SUMMARY echo "- CID: ${{ steps.storacha.outputs.cid }}" >> "$GITHUB_STEP_SUMMARY" echo "- URL: ${{ steps.storacha.outputs.url }}" >> "$GITHUB_STEP_SUMMARY" + +# Workflow run retention settings +retention-days: 30 \ No newline at end of file diff --git a/.github/workflows/secrets-check.yml b/.github/workflows/secrets-check.yml index 5e989082..b8d3b7e8 100644 --- a/.github/workflows/secrets-check.yml +++ b/.github/workflows/secrets-check.yml @@ -10,6 +10,7 @@ on: paths: - "k8s/**" +# Retention policy: Keep successful runs for 30 days, failed/cancelled for 7 days jobs: check-secrets-placeholders: name: Verify no real secrets in k8s manifests @@ -19,3 +20,6 @@ jobs: - name: Check backend-secret.yaml for non-placeholder values run: ./scripts/check-k8s-secrets.sh + +# Workflow run retention settings +retention-days: 30 \ No newline at end of file From f19abbe3bc3450bb811e707a53f6c5a1724d2e1b Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Fri, 25 Sep 2026 21:23:51 -0400 Subject: [PATCH 6/8] docs: align contributor setup with actual workspace --- CONTRIBUTING.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc8caa74..bd13e49f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,10 +78,11 @@ git clone https://github.com/Protocol-Guild/PayD.git cd PayD ``` -Install root/frontend dependencies: +Install root and frontend dependencies separately (the root workspace does not include `frontend/`): ```bash npm install +cd frontend && npm install && cd .. ``` Install backend dependencies: @@ -165,8 +166,7 @@ Health check: `GET http://localhost:3001/health` - **Linting**: ESLint (`npm run lint` in root/frontend; `npm run lint` in backend). - **Modules**: Backend uses ESM (`"type": "module"`). Prefer explicit `.js` extensions in relative TypeScript imports to match existing files. -- **Errors**: Prefer typed errors (`AppError` / subclasses in `backend/src/errors`) - and let the global error middleware format responses. Do not return raw +- **Errors**: Match the existing backend error response shape. Do not return raw database or stack messages to clients outside development. - **Security**: Never commit secrets. Sanitize logs (passwords, tokens, keys). Preserve tenant isolation middleware on multi-tenant routes. @@ -215,9 +215,9 @@ cargo test ### CI expectations -GitHub Actions (see `.github/workflows/`) run build, e2e, contract release, and -secrets checks. A PR should pass the same checks you can run locally before -requesting review. +GitHub Actions (see `.github/workflows/`) run checks according to event and +changed paths. Contract releases run on version tags, not every PR. Run the +focused checks relevant to your change before requesting review. ## Pull request process From e79e42da9825df698ae43749c25f30394666e5da Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Sat, 3 Oct 2026 12:50:00 -0400 Subject: [PATCH 7/8] docs: align PayD onboarding with existing startup scripts Separate the frontend Vite command from the root Stellar scaffold watcher, place frontend environment settings in its Vite project, and document one PORT=3000 local API setting matching the existing frontend proxy and health URL. Retain the backend's 3001 fallback when PORT is unset. Refs #561. Validation: exact package-script, backend config, example-env, frontend proxy, and Vite 7.2.6 root/envDir reconciliation; balanced Markdown fences, resolved relative links, unchanged guide sections outside setup. Docs only: no Node, application build/tests, or Prettier run during the shared runtime-capacity hold. No runtime/configuration files changed. --- CONTRIBUTING.md | 43 +++++++++++++++++++++++++++++++++---------- 1 file changed, 33 insertions(+), 10 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bd13e49f..63df7313 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,7 +66,7 @@ Install these before cloning: | **Node.js** 22+ | Frontend and backend | | **npm** (or yarn/pnpm) | Package management | | **Docker** (optional) | Local Postgres / Redis | -| **Rust** + **Stellar CLI** | Only needed for contract work | +| **Rust** + **Stellar CLI/scaffold tooling** | Root scaffold workflow or contract work | | **Git** | Branching and PRs | ## Local development setup @@ -99,19 +99,29 @@ Copy the example env files and edit secrets for your machine: ```bash cp .env.example .env +cp .env.example frontend/.env cp backend/.env.example backend/.env ``` +The root `.env` configures the scaffold workflow. Vite launched from `frontend/` +reads `frontend/.env`; configure its `PUBLIC_STELLAR_*` values for your network. +The [frontend Vite config](./frontend/vite.config.ts) uses Vite's default +[environment directory](https://vite.dev/config/shared-options#envdir). + +In `backend/.env`, keep one `PORT=3000` assignment and remove the duplicate `PORT` +entries copied from the example. This local setting matches the frontend's +`/api` proxy at `http://localhost:3000`. If you choose another API port, update +that proxy target and the health-check URL together. + Important backend variables (see `backend/.env.example`): -- `PORT` — API port (default `3001`) +- `PORT` — use `3000` for the local setup above; the + [backend config](./backend/src/config/index.ts) falls back to `3001` when unset - `DATABASE_URL` / `DB_*` — Postgres connection - `STELLAR_HORIZON_URL` / `STELLAR_NETWORK_PASSPHRASE` — network target - `SDS_*` — optional Stellar Data Service settings - `NODE_ENV` — `development` for verbose errors; never leak stacks in production -Frontend public vars are prefixed with `PUBLIC_STELLAR_*` in `.env.example`. - ### 3. Database Using Docker: @@ -133,22 +143,35 @@ npm run db:verify-schema ### 4. Run the apps -**Backend** (API on port 3001 by default): +Use separate terminals for the backend and frontend. Start each command block +below from the repository root. + +**Backend** (API on port 3000 with the local configuration above): ```bash cd backend npm run dev ``` -**Frontend** (Vite): +**Frontend** (standalone Vite project): ```bash -# from repo root +cd frontend npm run dev -# or -cd frontend && npm run dev ``` +This invokes `vite` via [frontend/package.json](./frontend/package.json). + +**Root scaffold workflow** (Stellar contract watcher and Vite): + +```bash +npm run dev +``` + +The root [package.json](./package.json) maps `dev` to `npm start`, which runs +`stellar scaffold watch --build-clients` and `vite` concurrently. Install the +Rust and Stellar CLI/scaffold tooling before using this workflow. + **Contracts** (optional): ```bash @@ -157,7 +180,7 @@ cargo build --release # or use Stellar CLI / scaffold workflows as documented in contract READMEs ``` -Health check: `GET http://localhost:3001/health` +Health check for the local configuration above: `GET http://localhost:3000/health` ## Code style and standards From 420d4bfe5783ea1666e637f5034f3b203af66c57 Mon Sep 17 00:00:00 2001 From: woahwhattheheck Date: Sat, 3 Oct 2026 13:09:58 -0400 Subject: [PATCH 8/8] docs: route README onboarding to the contributor guide Replace the malformed placeholder setup block with the real repository clone command and links to the maintained prerequisites, setup, testing, and PR guide. Keep the existing contributor guide and application source unchanged. --- README.md | 86 +++++++++++-------------------------------------------- 1 file changed, 17 insertions(+), 69 deletions(-) diff --git a/README.md b/README.md index 374ffef6..3f4400dc 100644 --- a/README.md +++ b/README.md @@ -144,72 +144,20 @@ Every payment includes: ## 🚀 Getting Started -### Prerequisites - -Ensure you have the following installed: - -- **Node.js** v22+ -- **npm** or **yarn** -- **Rust** (for Soroban contracts) -- **Stellar CLI** -- **Docker** (optional, for local development) - -### Installation - -1. **Clone the repository:** - ```bash - git clone [https://github.com/your-org/payD.git](https://github.com/your-org/payD.git) - cd payD - Install dependencies: - bash - npm install - Environment Setup: - bash - cp .env.example .env - ``` - -# Edit .env with your configuration - -Database Setup: -bash - -# Using Docker - -docker run --name payd-postgres -e POSTGRES_PASSWORD=mypassword -d postgres:15 - -# Or set up PostgreSQL manually - -Configuration -Edit -.env -with the following key variables: - -env - -# Stellar Network - -STELLAR_NETWORK=testnet # or mainnet -STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org - -# Database - -DATABASE_URL=postgresql://user:password@localhost:5432/payd - -# API Keys - -STELLAR_SECRET_KEY=your_issuer_secret_key -ANCHOR_API_KEY=your_anchor_service_key - -# JWT - -JWT_SECRET=your_jwt_secret -Development -Start the development server: -bash -npm run dev -Build for production: -bash -npm run build -Run tests: -bash -npm run test. +Start with the [contributor prerequisites](./CONTRIBUTING.md#prerequisites), then +clone the repository: + +```bash +git clone https://github.com/Protocol-Guild/PayD.git +cd PayD +``` + +Follow the [local development setup](./CONTRIBUTING.md#local-development-setup) +for dependency installation, environment files, database setup, and commands to +run the frontend, backend, and optional contract workflow. The guide distinguishes +standalone frontend Vite from the root Stellar scaffold workflow and keeps the +local API port aligned with the frontend proxy. + +Use the [testing guide](./CONTRIBUTING.md#testing-guide) for the commands for each +component, and the [pull request process](./CONTRIBUTING.md#pull-request-process) +when contributing a change.