Local Development Setup

Local Development SetupSetup: Drop — Fintech Payment App

Project: {{PROJECT_NAME}}Drop — Remittance + QR Payments Version: {{VERSION}}1.0 Date: {{DATE}}2026-02-23 Author: {{AUTHOR}}John (AI Director) Status: Draft | In Review | Approved Reviewers: {{REVIEWERS}}Alem Bašić (CEO)

Document History

Version	Date	Author	Changes
0.1	{{DATE}}2026-02-23	{{AUTHOR}}John	Initial draftlocal dev setup — Next.js 16 + SQLite + Vitest + Playwright

---

1. System Requirements

Software	Required Version	macOS	Linux	Windows (WSL2)
{{RUNTIME}}Node.js	{{VERSION}}20.x	brewnvm install {{RUNTIME}}20	aptnvm install {{RUNTIME}}20	Via WSL2 + nvm
Docker Desktopnpm	{{DOCKER_VERSION}}+10.x (with Node 20)	docker.comIncluded	docsIncluded	docsIncluded
Git	2.30+	Pre-installed	apt install git	Via WSL2
{{OTHER_TOOL}}flyctl	{{VERSION}}Latest	brew install {{OTHER_TOOL}}flyctl	fly.io/docs/flyctl/installing/	WSL2
Playwright browsers	Auto-installed	npx playwright install	{{LINUX_INSTALL}}npx playwright install	{{WINDOWS_INSTALL}}npx playwright install

Hardware minimum: {{MIN_RAM}}GB8GB RAM, {{MIN_DISK}}GB10GB free disk space (SQLite DB is small; bcrypt tests are CPU-intensive) Recommended: {{REC_RAM}}GB16GB RAM, SSD

Not supported: Windows without WSL2 (Next.js dev server requires Unix-compatible environment)

---

2. Quick Start (5 Steps)

# 1. CloneNavigate gitto cloneDrop {{REPO_URL}} &&app
cd {{REPO_NAME}}~/ALAI/products/Drop/src/drop-app

# 2. Install dependencies
{{INSTALL_CMD}}npm install

# 3. Configure environment
cp .env.example .envenv.local
# Edit .envenv.local — see Section 5 for required values

# 4. RunSet (withup Dockerdatabase forand dependencies)seed
{{START_CMD}}npm run db:migrate && npm run db:seed

# 5. VerifyStart opendevelopment server
npm run dev
# Open: http://localhost:{{PORT}}
# Should see: {{EXPECTED_LANDING}}3000

Total time (fast path): ~{{QUICKSTART_TIME}}5 minutes

If anything fails, read the full setup in Section 3 or check Common Issues.

---

3. Detailed Setup

3.1 RuntimeNode Version Manager

Tool: {{VERSION_MANAGER}}

# Install versionnvm manager(macOS {{VM_INSTALL_CMD}}with Homebrew)
brew install nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> ~/.zshrc
source ~/.zshrc

# Install requiredNode runtime20 version(Drop {{VM_USE_CMD}}requires {{RUNTIME_VERSION}}20+ #for SetNext.js as16)
nvm install 20
nvm use 20
nvm alias default {{VM_DEFAULT_CMD}} {{RUNTIME_VERSION}}20

# Verify
{{RUNTIME}}node --version  # Shouldv20.x.x
output:npm {{RUNTIME_VERSION}}--version   # 10.x.x

Auto-switching: The project root contains .{{VERSION_FILE}}nvmrc (e.g.,with .nvmrc20, .python-version). If your shell is configured, it switches automatically on cd into the project.

3.2 Package Manager Setup

# The projectDrop uses {{PKG_MANAGER}}npm # Install it if (not available:yarn {{PKG_MANAGER_INSTALL}}or # Install project dependenciespnpm)
cd {{REPO_NAME}}~/ALAI/products/Drop/src/drop-app
{{INSTALL_CMD}}npm install

# Verify installation
{{INSTALL_VERIFY_CMD}}npm list --depth=0  # Should show direct dependencies

Lockfile: {{LOCKFILE}}package-lock.json — committed to git. Do NOT delete it. Run {{INSTALL_CMD}}npm install (not {{FORCE_INSTALL_CMD}}npm install --force) to respect lockfile.

3.3 Database Setup

Drop

Optionuses A:SQLite for development and testing (no Docker (recommended)required).

# StartCreate/migrate database
containercd docker-compose~/ALAI/products/Drop/src/drop-app
upnpm -drun db:migrate
# Creates: ./local.db (SQLite file)

# Verify databasemigration
isnpm runningrun {{DB_CHECK_CMD}}db:migrate:status
# RunShould show all migrations {{MIGRATE_CMD}}applied

# Seed development data
{{SEED_CMD}}npm 

run

Option B: Local database install

# Install PostgreSQL (example)
brew install postgresql@{{PG_VERSION}}db:seed
# macOSInserts: #test or:users, sudomerchants, aptrecipients, installexchange postgresql-{{PG_VERSION}}  # Linux

# Start database
{{DB_START_LOCAL_CMD}}

# Create database
createdb {{DB_NAME}}_dev

# Run migrations
{{MIGRATE_CMD}}

# Seed development data
{{SEED_CMD}}rates

Verify database is set up:

{{DB_VERIFY_CMD}}# Check schema compliance
npm run test -- --testPathPattern=db.test.ts
# Should output:pass: {{DB_VERIFY_EXPECTED}}no balance column, no card_number/cvv

Note: SQLite file is in .gitignore. Each developer has their own local DB.

3.4 Environment Variables

# Copy the example file
cp .env.example .envenv.local

Edit .envenv.local with your local values:

Variable	Value for Local Dev	Notes
DATABASE_URL	{{LOCAL_DB_URL}}./local.db	UpdateSQLite withfile yourpath local(relative DBto credsapp root)
REDIS_URLJWT_SECRET	redis://localhost:6379Any 32+ char random string	DefaultUse ifopenssl usingrand Docker-base64 32
PORTNEXT_PUBLIC_SERVICE_MODE	{{PORT}}mock	ALWAYS mock for local dev
BCRYPT_ROUNDS	10	10 locally (faster); production uses 12
NEXT_PUBLIC_APP_URL	http://localhost:3000
NODE_ENVSUMSUB_API_KEY	developmentmock-key	Mocked in dev (no real API calls)
{{SECRET_VAR}}BAAS_API_KEY	—mock-key	AskMocked yourin onboardingdev buddy(no real BaaS calls)
RATE_LIMIT_MAX_AUTH	100	Higher locally to avoid blocking dev flow

Never commit .envenv.local: It's in .gitignore. Use .env.example for sharing template values.

3.5 SSLPlaywright CertificatesBrowser (If Needed Locally)Installation

# Install mkcertall brewPlaywright installbrowser mkcertbinaries #(required macOSfor #E2E or:tests)
aptnpx installplaywright mkcert  # Linux

# Install local CA
mkcert -install

# GenerateOr certinstall foronly localhostChromium mkcert+ localhost 127.0.0.1 ::1

# Move certs to projectWebKit (checkDrop .envE2E foruses expectedthese)
paths)npx mvplaywright localhost+2.peminstall {{CERT_PATH}}chromium mv localhost+2-key.pem {{KEY_PATH}}webkit

3.6 Seed Data Loading

After #npm Loadrun fixturedb:seed, data (fast, for unit/integration tests)
{{FIXTURE_CMD}}

# Load realistic development data (slower, ~{{SEED_SIZE}} records)
{{DEV_SEED_CMD}}

# Reset to clean state
{{RESET_CMD}}

Seededthese accounts afterexist running seed:locally:

Role	Email	Password	Notes
AdminConsumer (Amir)	[email protected][email protected]	{{SEED_PWD}}TestDrop123!	FullKYC accessapproved, active
UserMerchant (Ahmet)	[email protected][email protected]	{{SEED_PWD}}TestDrop123!	StandardMerchant registered
Pending KYC	[email protected]	TestDrop123!	kyc_status = pending
Fresh user	Register via UI	—	Create during testing

---

4. Running the Application

Development Server

# Start developmentNext.js dev server (with hot reload)reload
{{DEV_CMD}}npm run dev

# Application available at:
# http://localhost:{{PORT}}3000         — Landing page
# http://localhost:3000/login   — Login
# http://localhost:3000/api/health  — Health check (JSON)

What starts: {{DEV_WHAT_STARTS}}

Next.js dev

Watchserver Modeon /port Hot3000 Reload

with

Hothot reload isfor enabledall byroutes default(API in+ development. When you save a file:UI).

Useful

Backend:Dev {{BACKEND_RELOAD}}

Frontend: {{FRONTEND_RELOAD}}

Debug ModeCommands

npm run dev           # Start withdevelopment Node.jsserver
debuggernpm {{DEBUG_CMD}}run build         # ThenBuild attachproduction yourbundle
IDEnpm debuggerrun tostart         port# {{DEBUG_PORT}}Run production build locally
npm run lint          # ESLint
npm run type-check    # TypeScript type checking
npm run db:migrate    # Run pending migrations
npm run db:seed       # Seed test data
npm run db:reset      # Drop + recreate + seed (fresh state)

VS Code launch config: .vscode/launch.json — includes pre-configured debug targets.

Mobile Development (If Applicable)

# iOS Simulator (macOS only)
{{IOS_CMD}}

# Android Emulator
{{ANDROID_CMD}}

Requires: Xcode (iOS), Android Studio (Android)

---

5. Running Tests

All Tests (Recommended)

# Run all Vitest tests (unit + integration + performance)
npm run test

# Expected: 40+ tests passing across 11 test files

Unit Tests

# Run all unitVitest tests
{{UNIT_CMD}}npm run test

# Run tests in watch mode (re-runs on file save)
{{UNIT_WATCH_CMD}}npm run test:watch

# Run specific test file
{{UNIT_CMD}}npm {{TEST_FILE_PATH}}run test -- auth.test.ts

# Run tests matching pattern
{{UNIT_CMD}}npm run test -- --grep "{{PATTERN}}"bcrypt"

Integration Tests

# Requires database and Redis running (use Docker)
docker-compose up -d db redis

# Run integrationIntegration tests {{INT_CMD}}use real SQLite DB (auto-created in :memory: or temp file)
npm run test -- api-endpoints.test.ts db.test.ts middleware.test.ts

E2E Tests (Playwright)

# Requires fulldevelopment application stackserver running
{{DEV_CMD}}npm run dev &  # Or start in separate terminal

# Run all Playwright E2E tests
(headless)npx {{E2E_CMD}}playwright test

# Run E2Especific project
npx playwright test --project=user-flows
npx playwright test --project=full-flows
npx playwright test --project=input-chaos

# Run with browser visible (useful for debugging)
{{E2E_HEADED_CMD}}npx playwright test --headed

# RunOpen specificPlaywright E2EUI mode
npx playwright test {{E2E_CMD}} --grep "{{PATTERN}}"ui

TestPerformance Benchmarks

# Run api-benchmarks.test.ts
npm run test -- api-benchmarks.test.ts

# Expected outputs (NFR targets):
# bcrypt hash: < 1,000ms
# DB SELECT: < 10ms
# DB INSERT: < 20ms
# 50 concurrent rate limit checks: < 2,000ms total

Coverage Report

{{COV_CMD}}npm run test:coverage

# Report generated at: {{COV_REPORT_PATH}}
# Open in browser:coverage/index.html
open {{COV_REPORT_PATH}}/coverage/index.html

---

6. Common Issues & Solutions

db

Problem	Likely Cause	Solution
Module not foundfound: next	Dependencies not installed	Run {{INSTALL_CMD}}npm install
Database connectionfile refusednot found	DBMigrations not runningrun	Run docker-composenpm uprun -ddb:migrate
JWT_SECRET is required	Missing env var	Copy .env.example → .env.local; set JWT_SECRET
Port {{PORT}}3000 already in use	Another process using the port	lsof -ti:{{PORT}}3000 | xargs kill
Permission denied: .env	File permission issue	chmod 600 .env
Node version mismatch	Wrong Node version active	{{VERSION_MANAGER}}nvm use {{NODE_VERSION}}20
Slowbcrypt performancetests onvery Dockerslow (macOS)> 2s each)	DockerBCRYPT_ROUNDS=12 Desktopin volume mountsenv	EnableSet VirtioFSBCRYPT_ROUNDS=10 in Docker Desktop settings.env.local
EACCES:Playwright permissiontests denied,fail: mkdir"browser node_modulesnot found"	npm global prefix issue	See npm fix
Tests failing with timeout	Integration test DBBrowsers not runninginstalled	docker-composenpx upplaywright -dinstall
SSL:database certificateis verify failedlocked	MissingConcurrent certwrites orin mkcertSQLite not installedtest	Re-Expected under high concurrency; run mkcerttests setupserially: (Sectionnpm 3.5)run test -- --pool=forks
MigrationNEXT_PUBLIC_SERVICE_MODE=live alreadyaccidentally appliedset	Wrong env var	Always use mock locally; live requires real BaaS
TypeScript error on any	StaleStrict migration statemode	Add proper type; never use {{MIGRATION_ROLLBACK_CMD}}any then re-run

Still stuck? Ask inJohn #{{DEV_CHANNEL}}(AI Director) via Mission Control or ping#drop yourSlack onboarding buddy.channel.

---

7. DockerProject Setup (Alternative)

7.1 docker-compose.ymlStructure Reference

#~/ALAI/products/Drop/src/drop-app/
Start├── allsrc/
services│   docker-compose├── upapp/                     # StartNext.js onlyApp backendRouter
services│   │   ├── api/                 # 26 API routes
│   │   │   ├── auth/            # register, login, logout, me, otp, pin
│   │   │   ├── transactions/    # remittance, qr-payment, list
│   │   │   ├── rates/           # exchange rates (db,6 redis,corridors)
etc.)│   docker-compose│   up│   ├── merchants/       # register, me
│   │   │   ├── cards/           # list, get (feature-flagged)
│   │   │   └── health/          # health check
│   │   └── (app)/               # Protected app pages
│   ├── components/              # Shared UI components
│   ├── lib/                     # Utilities, helpers, auth, db redisclient
│   └── middleware.ts            # RebuildRate afterlimiting, DockerfileCSRF, changesauth docker-composemiddleware
up├── --builddb/
│   ├── migrations/              # StopSQL migration files
│   └── seeds/                   # Seed data
├── __tests__/
│   ├── auth.test.ts             # bcrypt, JWT, password validation
│   ├── api-endpoints.test.ts    # All 26 API routes
│   ├── db.test.ts               # Schema compliance (no balance, no CVV)
│   ├── middleware.test.ts       # Rate limiting, auth middleware
│   ├── validation.test.ts       # Input validation, XSS, injection
│   ├── transactions.test.ts     # Fee calculations, transaction logic
│   ├── rates.test.ts            # Exchange rates API
│   ├── api-benchmarks.test.ts   # Performance benchmarks
│   ├── feature-flags.test.ts    # Feature flag behavior
│   ├── regression-suite.test.ts # Regression tests
│   ├── sumsub-integration.test.ts # KYC mock integration
│   ├── cards-integration.test.ts  # Cards feature (feature-flagged)
│   └── e2e/
│       ├── user-flows.spec.ts   # Registration, login journeys
│       ├── full-flows.spec.ts   # Remittance, QR payment journeys
│       └── input-chaos.spec.ts  # 20+ edge case inputs
├── .env.example                 # Environment variable template
├── vitest.config.ts             # Vitest configuration
├── playwright.config.ts         # Playwright configuration (3 projects)
├── next.config.ts               # Next.js configuration
└── package.json                 # Scripts and remove containers
docker-compose down

# Stop and remove containers + volumes (reset state)
docker-compose down -vdependencies

Services defined in docker-compose.yml:

Service	Port	Description
app	{{PORT}}	Main application
db	{{DB_PORT}}	PostgreSQL database
redis	6379	Redis cache
{{OTHER}}	{{PORT}}	{{DESCRIPTION}}

7.2 Volume Mounts

Local Path	Container Path	Purpose
.	/app	Source code (hot reload)
db-data	/var/lib/postgresql/data	Database persistence
node_modules	/app/node_modules	Isolated from host

7.3 Port Mappings

Host Port	Container Port	Service
{{PORT}}	{{PORT}}	Application
{{DB_PORT}}	5432	PostgreSQL
6379	6379	Redis

---

8. IDE Configuration

8.1VS RecommendedCode ExtensionsSettings (VS Code).vscode/settings.json)

#{
  Install"editor.formatOnSave": alltrue,
  at"editor.defaultFormatter": once"esbenp.prettier-vscode",
  cat .vscode/extensions.json | jq '.recommendations[]' | xargs -I{} code --install-extension"editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

Recommended Extensions

Extension	ID	Purpose
{{EXT_1}}	{{ID}}	{{PURPOSE}}
{{EXT_2}}	{{ID}}	{{PURPOSE}}
{{EXT_3}}	{{ID}}	{{PURPOSE}}
ESLint	dbaeumer.vscode-eslint	Inline linting
Prettier	esbenp.prettier-vscode	Format on save

8.2 Debug Configurations

The project includes .vscode/launch.json with these pre-built debug targets:

runningprocess

Configuration	What it does
Tailwind CSS IntelliSense	Debug: API Serverbradlc.vscode-tailwindcss	StartsAutocomplete APIfor with debugger attached on port {{DEBUG_PORT}}Tailwind
Playwright Test	Debug: Testsms-playwright.playwright	RunsRun/debug testPlaywright suite with breakpoints supportedtests
Vitest	Attach to Processvitest.explorer	AttachRun/debug debuggerVitest totests
TypeScript Error Lens	usernamehw.errorlens	Inline TypeScript errors

8.3 Workspace Settings

.vscode/settings.json (committed to repo):

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "{{FORMATTER_ID}}",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib"
}

---

Related Documents

• Developer Onboarding Guide
• Coding Standards
• EnvironmentTesting ConfigurationGuide

---

Approval

Role	Name	Date	Signature
Author	John (AI Director)	2026-02-23	Approved (AI)
ReviewerTech Lead	John	2026-02-23	Approved
ApproverCEO (Alem)	Alem Bašić	TBD