Developer Onboarding Guide

Welcome to Evergrn. This guide will get your development environment running on a Windows machine from scratch. You do not need any prior setup — the script handles installing everything.

Before You Start

You need two things from your team lead before you begin:

An Azure DevOps invitation — check your work email for an invitation to dev.azure.com/evergrn. Accept it and sign in with your @evergrn.co Microsoft account before running the script.
The .env file — this file contains passwords and API keys. Your team lead will send it to you securely (not over email). Keep it private — never share it, post it online, or commit it to the repo.

Step 1 — Run the Setup Script

The setup script installs all required software and downloads the codebase automatically.

Download the file dev-setup.ps1 from the repo or ask your team lead to send it to you.
Right-click the file and choose "Run with PowerShell".
- If Windows asks "Do you want to allow this app to make changes?", click Yes.
- If you see a message about execution policy, open PowerShell as Administrator and run:
```
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```
  Then try running the script again.
Follow the prompts. When asked where to put the project, press Enter to accept the default (C:\Users\YourName\Projects\evergrn), or type a different path.
A browser window will open for Azure DevOps sign-in. Log in with your @evergrn.co account.
The script will run for several minutes while it downloads dependencies. This is normal.

The script installs:

Software	What it's for
Git	Downloads the codebase and tracks code changes
Node.js 22 LTS	Runs the API server and web/mobile tools
Visual Studio Code	The code editor everyone on the team uses
Azure CLI	Used for deploying code to the cloud

Step 2 — Fill in the `.env` File

After the script finishes, it creates a .env file in the project folder. This file tells the API how to connect to the database, payment system, and email service.

Open VS Code:

code C:\Users\YourName\Projects\evergrn

In the file tree on the left, click .env.
Replace each placeholder value with the real values from your team lead.

The file looks like this — do not share or commit these values:

DATABASE_URL="postgresql://..."       ← Azure PostgreSQL connection string
JWT_SECRET="..."                      ← Long random string for auth tokens
STRIPE_SECRET_KEY="sk_test_..."       ← Stripe test key
STRIPE_WEBHOOK_SECRET="whsec_..."     ← Stripe webhook secret
ACS_CONNECTION_STRING="endpoint=..."  ← Azure email service
ACS_SENDER="noreply@evergrn.co"       ← Sender address (this one is fixed)
APP_URL="http://localhost:5173"        ← Leave as-is for local dev
AZURE_STORAGE_CONNECTION_STRING="..." ← Azure file storage

Step 3 — Start the Dev Servers

The project has three pieces that each need their own terminal window:

Terminal 1 — API Server

cd C:\Users\YourName\Projects\evergrn
npm run dev

You should see:

Server running on port 3000

Terminal 2 — Web App

cd C:\Users\YourName\Projects\evergrn\client
npm run dev

Open your browser and go to http://localhost:5173

Terminal 3 — Mobile App (optional)

cd C:\Users\YourName\Projects\evergrn\mobile
npm start

Install the Expo Go app on your iPhone, then scan the QR code that appears in the terminal. The mobile app will load on your phone over your local Wi-Fi.

The mobile app also works against the live Azure API — you do not need to run the API server locally to test mobile. See mobile\src\api.js to switch between the two.

Project Layout

evergrn\
├── server.js          The API entry point — start with "npm run dev" in this folder
├── .env               Your local secrets — never commit this file
├── src\               All API code (routes, middleware, config)
├── prisma\            Database schema
├── client\            Web app — start with "npm run dev" inside this folder
├── mobile\            iOS app — start with "npm start" inside this folder
└── current-documentation\   Project docs — start here to understand the codebase

Useful Commands

Command	Where to run it	What it does
`npm run dev`	`evergrn\`	Starts the API server with auto-reload
`npm run dev`	`evergrn\client\`	Starts the web app
`npm start`	`evergrn\mobile\`	Starts the mobile app via Expo
`npx prisma studio`	`evergrn\`	Opens a visual database browser at localhost:5555
`npx prisma migrate dev`	`evergrn\`	Applies any new database schema changes

Frequently Asked Questions

The API won't start and shows a database error. Your DATABASE_URL in .env is incorrect or missing. Double-check it with your team lead.

The web app shows a blank page or network errors. Make sure the API server is running in a separate terminal (port 3000). The web app talks to it at http://localhost:3000.

The mobile app says "Unable to connect to API". By default the mobile app talks to the live Azure API — it does not need your local API server. If you changed BASE_URL in mobile\src\api.js, change it back to the Azure URL.

"Execution policy" error when running the setup script. Open PowerShell as Administrator (search "PowerShell", right-click, "Run as administrator") and run:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

Then try the script again.

I pulled new code and something broke. Run these in order from the evergrn\ folder:

npm install
npx prisma generate

If there were database schema changes you'll also see a message telling you to run npx prisma migrate dev.

I need to deploy my changes to Azure. See current-documentation\cloud-infrastructure.md for the full deployment process. In short: run python make_deploy_zip.py, upload the resulting deploy3.zip to Azure Blob Storage, then restart the App Service. Ask your team lead before deploying — all changes go through a pull request first.

Onboarding