Developer Onboarding Guide

Developer Onboarding GuideGuide: 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 draftonboarding guide — AI-native team (Builder + Validator agents)

---

Welcome

Welcome to {{PROJECT_NAME}}Drop! This— remittance + QR payments for everyone in Scandinavia.

Drop is built by an AI-native team at ALAI Holding AS. Our team structure is unusual: John (AI Director, Claude Opus) coordinates Builder agents (Claude Sonnet) and Validator agents (Claude Sonnet, read-only). Alem Bašić (CEO) provides direction and final approvals.

If you are a new Builder or Validator agent joining a Drop task, this guide will helpget you gooriented fromquickly. zero to a fully working development environment and your first contribution.

If anything in this guide is unclear or out of date, please update it as you go — good documentation is a team responsibility. Your onboarding buddy is {{BUDDY}} — reach out to them anytime.go.

Your first weeksession at a glance:

• DayStep 1: Read this guide + CLAUDE.md in the project root
• Step 2: Set up yourlocal environment and(Section get2) the+ appverify runningtests locallypass
• DayStep 2-3: Read the architecture overview,overview explore(Section the codebase4)
• DayStep 4-5:4: WorkPick throughup your firstassigned smallMission ticketControl with your buddy's guidancetask

---

1. Prerequisites

Hardware Requirements

Component	Minimum	Recommended
CPU	{{MIN_CPU}}4 cores	{{REC_CPU}}8+ cores (bcrypt is CPU-intensive in tests)
RAM	{{MIN_RAM}}GB8GB	{{REC_RAM}}GB16GB
Disk	{{MIN_DISK}}GB10GB free	SSD with {{REC_DISK}}GB20GB free
OS	{{SUPPORTED_OS}}macOS (primary), Linux, Windows (WSL2)	macOS

Accounts You Need

Account	Why	How to Get Access
GitHub / GitLab(alai-org)	Code repository	Ask {{GITHUB_ADMIN}}John (AI Director)
{{CLOUD_PROVIDER}}Fly.io	CloudStaging resourcesdeployment (drop-app)	RequestAsk viaJohn {{CLOUD_REQUEST_PROCESS}}(AI Director)
{{CI_CD_PLATFORM}}Vaultwarden (vault.basicconsulting.no)	CI/CDSecrets pipeline/ credentials	Auto-provisionedAsk onJohn org(AI inviteDirector)
{{ERROR_TRACKER}}	Error monitoring	Ask {{SENTRY_ADMIN}}
{{PROJECT_MGMT}}	Tickets / tasks	Ask {{PM_ADMIN}}
{{COMMUNICATION}}alai-talk.slack.com	Team communication	Ask yourAlem managerBašić (CEO)
VaultMission Control (node ~/ Secretssystem/tools/mc.js)	DevelopmentTask secretsmanagement	AskLocal {{VAULT_ADMIN}}system tool

Expected setup time for all accounts: {{ACCOUNT_SETUP_TIME}}1 days

Access Requests

agentsareprovisioned

Access Type	Contact	Process	SLA
GitHub organization	{{CONTACT}}	{{PROCESS}}	{{SLA}}
Cloud consolesession (read-onlyAI dev)	{{CONTACT}}	{{PROCESS}}	{{SLA}}
VPN	{{CONTACT}}	{{PROCESS}}	{{SLA}}
Production read access	{{CONTACT}}	Requires security training first	{{SLA}}

per-task)

---

2. Development Environment Setup

2.1 macOS Setup

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install requiredNode.js tools
brew install {{TOOLS_LIST}}
# e.g.: brew install git nodevia nvm docker kubectl terraform

# Install nvm (Node version manager)
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 20 (Drop uses Next.js 16 which requires Node version20+)
nvm install {{NODE_VERSION}}20
nvm use {{NODE_VERSION}}20
nvm alias default {{NODE_VERSION}}20

2.2 Linux Setup

# Update package index
sudo apt update && sudo apt upgrade -y

# Install required tools
sudo apt install -y {{LINUX_TOOLS}}

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v{{NVM_VERSION}}/v0.39.7/install.sh | bash
source ~/.bashrc

# Install required Node version20
nvm install {{NODE_VERSION}}20
nvm use 20

2.3 Windows Setup

# Enable WSL2
wsl --install

# After WSL2 is set up, follow the Linux setup instructions inside WSL2
# Recommended: Use VS Code with Remote WSL extension

2.4 Required Software & Versions

Software	Required Version	Install
Node.js	{{NODE_VERSION}}20.x	nvm install {{NODE_VERSION}}20
npm / yarn / pnpm	{{PKG_MGR_VERSION}}10.x (included with Node 20)	Included with Node
Dockerflyctl	Latest	{{DOCKER_VERSION}}+brew install flyctl	docker.com/get-docker(for staging access)
DockerPlaywright Composebrowsers	Latest	{{COMPOSE_VERSION}}+npx playwright install	Included with Docker Desktop
{{OTHER_TOOL}}	{{VERSION}}	{{INSTALL_CMD}}

Check your versions:

node --version    # Should be v{{NODE_VERSION}}v20.x.x
dockernpm --version     # Should be {{DOCKER_VERSION}}+10.x.x

2.54 IDE Setup

Recommended IDE: {{IDE}}VS Code

Required extensions:

# VS Code — install all recommended extensions
code --install-extension {{EXTENSION_1}}
code --install-extension {{EXTENSION_2}}
code --install-extension {{EXTENSION_3}}
# OR: Open project in VS Code → "Install recommended extensions" prompt will appear

Recommended extensions:

Extension	Purpose
{{EXT_1}}dbaeumer.vscode-eslint	{{PURPOSE}}ESLint inline linting
{{EXT_2}}esbenp.prettier-vscode	{{PURPOSE}}Format on save
{{EXT_3}}bradlc.vscode-tailwindcss	{{PURPOSE}}Tailwind CSS IntelliSense
ms-playwright.playwright	Playwright test runner
vitest.explorer	Vitest test explorer

2.65 Environment Variables

# Copy the example env file
cp src/drop-app/.env.example src/drop-app/.envenv.local

# Fill in your local values
# AskRetrieve yourfrom onboardingVaultwarden: buddyvault.basicconsulting.no
for# anyCLI: valuesbw markedget {{SECRET}}item "Drop Dev .env" --session $(cat /tmp/bw-session)

Key variables to set:variables:

Variable	WhatValue tofor putLocal Dev	Where to get itNotes
DATABASE_URL	postgresql:.//localhost:5432/{{APP}}_devlocal.db (SQLite)	LocalAuto-created setupon first migration
{{SECRET_VAR}}JWT_SECRET	YourAny devrandom secret32+ char string	AskNEVER {{BUDDY}}use in production
NEXT_PUBLIC_SERVICE_MODE	mock	Always mock for local dev
BCRYPT_ROUNDS	10	Use 10 locally (faster); production uses 12
SUMSUB_API_KEY	mock	Mocked in dev
BAAS_API_KEY	mock	Mocked in dev

Never commit .env.local: It's in .gitignore.

---

3. Repository Setup

# Step 1: CloneNavigate theto repositoryDrop gitapp clone {{REPO_URL}}directory
cd {{REPO_NAME}}~/ALAI/products/Drop/src/drop-app

# Step 2: Install dependencies
{{INSTALL_CMD}}  # npm install / yarn / pnpm install

# Step 3: Set up the database
{{DB_SETUP_CMD}}  # e.g., npm run db:create &&
npm run db:migrate

# Step 4: Seed development data
{{SEED_CMD}}  # e.g.,
npm run db:seed

# Step 5: Configure environment (see 2.6)5)
cp .env.example .envenv.local
# Edit .envenv.local with your values

# Step 6: Start the applicationdevelopment {{DEV_CMD}}  # e.g.,server
npm run dev

# Step 7: Open the application
open http://localhost:{{PORT}}3000
# Expected: Drop landing page or login screen

---

4. Architecture Overview

High-level architecture: SeeDrop deployment-architecture.mdis a PSD2 pass-through fintech app — it NEVER holds customer money.

CRITICAL — Read Before Writing Any Code:

Drop uses an AISP/PISP pass-through model (ADR-003). The users table MUST NOT have a balance column. The cards table MUST NOT have card_number or cvv columns. These are tested in db.test.ts on every commit. Violating this is a P0 incident.

In brief:

• Frontend: {{FRONTEND_STACK}}Next.js 16 (App Router), React 19, TypeScript, Tailwind CSS — located in {{FRONTEND_DIR}}src/drop-app/
• Backend: {{BACKEND_STACK}}Next.js API Routes (26 routes) — located in {{BACKEND_DIR}}src/drop-app/src/app/api/
• Database: {{DB_ENGINE}}SQLite (dev) → PostgreSQL (Phase 1 production) — schema in {{SCHEMA_DIR}}src/drop-app/db/
• Key external services: {{EXTERNAL_SERVICES}}Mock BaaS (AISP + PISP), Mock Sumsub KYC, exchange rates (static seed)
• Deployment: Fly.io (Stockholm region) for backend; Vercel for landing page
• Auth: JWT in httpOnly cookie, SameSite=Strict, 7-day expiry; bcrypt 12 rounds

Codebase tour (key directories):

Directory	Purpose
{{DIR_1}}src/drop-app/src/app/api/	{{PURPOSE_1}}26 API routes (auth, transactions, rates, merchants, cards, health)
{{DIR_2}}src/drop-app/src/app/(app)/	{{PURPOSE_2}}App pages (dashboard, send money, QR scan, history, profile)
{{DIR_3}}src/drop-app/src/components/	{{PURPOSE_3}}Shared UI components (drop-logo.tsx, etc.)
{{DIR_4}}src/drop-app/db/	{{PURPOSE_4}}SQLite schema, migrations, seed scripts
src/drop-app/__tests__/	14 test files (unit, integration, performance, E2E)
mockups/figma-make-export/	UI source of truth (10 screens — ALWAYS check here before UI changes)

---

5. Key Documentation Links

Document	Link	Purpose
ArchitectureProject overview	deployment-architecture.CLAUDE.md	HowPass-through themodel systemrules, isbranding, structuredfeatures
API DocumentationReference	{{API_DOCS_LINK}}docs/backend/API-REFERENCE.md	All 26 API referenceendpoints
DesignDatabase SystemSchema	{{DESIGN_SYSTEM_LINK}}docs/backend/DATABASE-SCHEMA.md	UITable componentsdefinitions, compliance rules
Architecture	project/architecture/drop-architecture.md	System design, ADRs
Testing Guide	docs/testing/TESTING-GUIDE.md	How to run Vitest + Playwright
Test Inventory	docs/testing/TEST-INVENTORY.md	All 14 test files documented
Coding Standards	coding-standards.md	How we write code
TestDefinition Strategyof Done	test-strategy.docs/templates-testing/definition-of-done.md	HowWhat we"done" testmeans
CI/CDSecurity PipelineAudit	cicd-pipeline.project/docs/security-qa-audit.md	HowKnown deploymentsissues work+ status
Tech Decisions (ADRs)Roadmap	{{ADR_DIR}}ROADMAP.md	WhyPhases we0/0.5/1/2/3 made+ key decisionsblockers

---

6. Coding Standards Reference

Standards document: coding-standards.md

Quick reference:

• Language: TypeScript — strict mode, no any
• Commit messages: Conventional Commits format (feat:, fix:, docs:test:, etc.)
• Branch naming: feature/MC-{{BRANCH_FORMAT}} (e.g., feature/TICKET-123-task-id}-short-description)
• PR size: Aim for < {{PR_SIZE}}300 lines changed per PR
• Testing requirement:Testing: AllEvery PRsPR requiremust include tests for new code
• SQL: Parameterized queries ONLY — never string concatenation
• Passwords: bcrypt ONLY — SHA-256 is explicitly rejected in auth.test.ts

---

7. Git Workflow & Branching Strategy

# Create a feature branch (aligned to Mission Control task)
git checkout -b feature/MC-{{TICKET}}task-id}-description

# Make changes, then commit using Conventional Commits
git add {{FILES}}src/drop-app/...
git commit -m "feat({{SCOPE}})auth): describeadd whatbcrypt yourounds did"configuration"

# Push your branch
git push origin feature/MC-{{TICKET}}task-id}-description

# Open a PR viato GitHub/GitLabmain UIbranch

Branching strategy: {{STRATEGY}} — see CI/CD Pipeline

PR requirements:

1. Title follows format:Conventional Commits: type(scope): description
2. PRAll descriptionVitest filledtests inpassing (templatenpm auto-loaded)run test)
3. TestsTypeScript includedcompiles for(npm newrun codetype-check)
4. CIESLint pipelinepasses passing(npm beforerun requesting reviewlint)
5. AtValidator least {{REVIEW_COUNT}} reviewer(s)agent approved (read-only review)

---

8. First PRTask Checklist

Your first PR goal: A small, low-risk change to confirm everything works end-to-end.

• Development environment running locally (npm run dev at http://localhost:3000)
• CanTest suite passing: npm run thetest full(40+ testVitest suite:tests {{TEST_CMD}}all green)
• AllE2E tests passingpassing: locallynpx playwright test (3 projects)
•  Read CLAUDE.md in ~/ALAI/products/Drop/ — understand pass-through model
•  Read docs/testing/TESTING-GUIDE.md — understand test structure
•  Mission Control task assigned and marked in_progress
• First branchchange createdincludes followingappropriate naming conventiontests
• ChangeDefinition madeof (startDone smallchecklist —completed abefore docmarking fixtask or minor improvement is perfect)
•  Tests written for any logic change
•  PR opened with filled description
•  CI pipeline passing on your PR
•  Review requested from your onboarding buddy
•  First PR merged 🎉done

---

9. Team Rituals & MeetingsCommunication

Drop uses an AI-native async workflow:

MeetingCommunication Type	Frequency	When	Purpose	Required
Daily standup	Daily	{{TIME}}	Status, blockers	Yes
Sprint planning	{{SPRINT_FREQ}}	{{TIME}}	Plan upcoming sprint	Yes
Sprint review	{{SPRINT_FREQ}}	{{TIME}}	Demo completed work	Yes
Retrospective	{{SPRINT_FREQ}}	{{TIME}}	Process improvement	Yes
Architecture review	Monthly	{{TIME}}	Tech decisions	Optional
Social / team coffee	{{SOCIAL_FREQ}}	{{TIME}}	Team building	Encouraged

---

10. Communication Channels

Channel	Platform	Purpose
#{{GENERAL_CHANNEL}}Task coordination	{{PLATFORM}}Mission Control (node ~/system/tools/mc.js)	GeneralAll teamtask communicationassignments, status
#{{DEV_CHANNEL}}Technical decisions	{{PLATFORM}}comms/decisions/ in the repo	DeveloperArchitecture discussions,decisions, code helpADRs
#{{INCIDENTS_CHANNEL}}CEO updates	{{PLATFORM}}MCP email (John → [email protected])	IncidentBusiness responsemilestones, blockers
#{{DEPLOYMENTS_CHANNEL}}Engineering	{{PLATFORM}}alai-talk.slack.com #drop	DeploymentEngineering notificationsdiscussions
DirectSecurity messageissues	{{PLATFORM}}alai-talk.slack.com #drop-security	QuickImmediate questions to teammates
{{EMAIL_LIST}}`	Email	Formal announcementsescalation

Rule:No daily standups Default— toasync publicby channelsdefault. overJohn DMs.(AI QuestionsDirector) askedcoordinates invia channelsMission help the whole team.Control.

---

11.10. Key Contacts

Director/ assignment,code

Role	Name	Contact	Help With
OnboardingAI Buddy	{{BUDDY}}	{{CONTACT}}	Everything in the first week
Tech Lead	{{TECH_LEAD}}John (Claude Opus)	{{CONTACT}}Mission Control DM	TechnicalArchitecture, decisions,task architecture
Engineering Manager	{{ENG_MGR}}	{{CONTACT}}	Career, process, team
DevOps / Platform	{{DEVOPS}}	{{CONTACT}}	Infrastructure, deployment, CIreview
QA Lead	{{QA_LEAD}}Validator Agent	{{CONTACT}}Task coordination	TestingTest questionsreview, compliance checks
CEO / Product Owner	Alem Bašić	[email protected]	Business decisions, UAT sign-off

---

Related Documents

• Local Development Setup
• Coding Standards
• Developer Offboarding Guide
• Definition of Done

---

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