Development Environment Setup

This guide walks you through setting up a local development environment for Arda on macOS. By the end you will have the workspace cloned, toolchains installed, secrets configured, and each repository building successfully.

Prerequisites

Install the following tools before cloning any repositories. All commands assume macOS with Homebrew available.

Homebrew

If Homebrew is not installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Node.js

Install Node.js v20 or later. The recommended approach is nvm so you can switch versions per project:

brew install nvm
nvm install 20
nvm use 20
nvm alias default 20

Alternatively, install directly via Homebrew:

brew install node@20

JDK 21

Install Eclipse Temurin 21 (the distribution used in CI):

brew install --cask temurin@21

Verify:

java -version
# openjdk version "21.x.x" ...

Gradle

Backend repositories include a Gradle wrapper (./gradlew) and do not require a system-level Gradle installation. If you want the gradle command available globally for convenience:

brew install gradle

Docker or Rancher Desktop

Backend services use TestContainers for integration tests and can be deployed to a local Kubernetes cluster. Install one of the following:

Docker Desktop — https://www.docker.com/products/docker-desktop
Rancher Desktop — https://rancherdesktop.io (open source alternative)

kubectl and Helm

Required for deploying backend services to local Kubernetes:

brew install kubectl helm

1Password CLI

Secrets (API keys, database credentials, environment-specific configuration) are managed through 1Password. Install the CLI and authenticate:

brew install --cask 1password/tap/1password-cli
op signin

Verify:

op whoami

You must be a member of the Arda 1Password team and have access to the Arda Dev vault before secret-injected commands will work.

Git

macOS ships with Git. Confirm the version is 2.35 or later (worktree commands require this):

git --version

If you need a newer version:

brew install git

AWS CLI v2

Required for services that interact with AWS resources and for SSO-authenticated deployments:

brew install awscli
aws configure sso

Follow the prompts to configure your SSO profile. The profile name used in Makefile targets is arda-dev — match that name during setup.

Setting Up the Workspace

The Arda workspace is a parent directory containing sibling repositories. A bootstrap script automates the setup.

Quick Start (Recommended)

1. Clone the workspace control plane:

mkdir -p ~/code/arda
cd ~/code/arda
git clone git@github.com:Arda-cards/workspace.git

2. Run the bootstrap script:

bash workspace/scripts/bootstrap-workspace.sh --role full --ssh

The --role flag controls which repositories are cloned:

Role	Repositories
`full`	All repositories (default)
`backend`	Backend services + shared libraries + infrastructure + API tests + docs
`frontend`	Frontend apps + component library + docs
`minimal`	Workspace + documentation only

The script is idempotent — safe to re-run if you add repos later or switch roles.

What the Bootstrap Script Does

Creates symlinks at the workspace root:
- CLAUDE.md → workspace/CLAUDE.md (AI agent instructions)
- GEMINI.md → workspace/AGENTS.md (Gemini CLI instructions)
- .claude → workspace/instructions/claude (agent configuration)
Creates projects/ and scratch/ directories
Clones repositories based on your role
Installs pre-commit hooks for documentation and workspace repos (manifest auto-regeneration)

After setup, your workspace looks like:

arda/
├── CLAUDE.md           → workspace/CLAUDE.md
├── GEMINI.md           → workspace/AGENTS.md
├── .claude             → workspace/instructions/claude
├── workspace/
├── documentation/
├── operations/
├── arda-frontend-app/
├── projects/
├── scratch/
└── ...

Manual Setup

If you prefer to set things up manually or need to add a single repository:

# Clone a specific repo
git clone git@github.com:Arda-cards/<repo-name>.git

# Install hooks for repos that have them
cd documentation && make install-hooks && cd ..
cd workspace && make install-hooks && cd ..

1Password Environment Files

Secrets are not stored in .env files in source control. Instead, each repository contains one or more 1Password*.env files that map environment variable names to 1Password secret references. The op run command injects the resolved secrets at process startup.

Backend Repositories

Backend repositories (operations, common-module, accounts-component) use a single 1Password.env file at the repository root:

# Build and deploy with secrets injected
op run --env-file=1Password.env -- ./gradlew build
op run --env-file=1Password.env -- ./gradlew helmInstallToLocal

api-test Repository

The api-test repository has one file per environment under 1Password/:

api-test/
└── 1Password/
    ├── dev.env
    ├── stage.env
    ├── prod.env
    └── local.env

# Run tests against dev
op run --env-file=1Password/dev.env -- make test-dev

# Run tests against local Kubernetes
op run --env-file=1Password/local.env -- make test-local

1Password Vault Reference

Vault	Contents	Used By
`Arda Dev`	API keys, database credentials, JWT signing keys	Backend repos, api-test
`Arda Infrastructure`	AWS access credentials, Helm chart values	infrastructure, deployments

Contact a team lead to get vault access if op run fails with “item not found” errors.

IDE Setup

IntelliJ IDEA (Kotlin Backend)

IntelliJ IDEA is the recommended IDE for Kotlin backend repositories. After cloning:

Open IntelliJ IDEA and choose File > Open.
Navigate to the repository root (e.g., ~/code/arda/operations) and open the build.gradle.kts file as a project.
Allow IntelliJ to import the Gradle project and download dependencies. This may take several minutes on first import.
Confirm that the project SDK is set to JDK 21: File > Project Structure > Project > SDK.

For composite builds (changes spanning common-module and a consuming service), see Multi-Repository Gradle Development.

VS Code (Frontend and AI-Assisted Work)

VS Code is recommended for frontend repositories and for working with Claude Code:

brew install --cask visual-studio-code

Recommended extensions:

ESLint — for TypeScript and React linting
Prettier — for code formatting
Tailwind CSS IntelliSense — for ux-prototype development
Claude Code (anthropics.claude-code) — for AI-assisted development

Both IntelliJ IDEA and VS Code can be open simultaneously on the same workspace without conflict. A common setup is IntelliJ for backend work and VS Code as the Claude Code terminal host.

Local Kubernetes (Optional)

Full-stack local development requires a running Kubernetes cluster. This is optional for frontend-only or documentation-only work.

1. Enable Kubernetes in Docker Desktop or Rancher Desktop:

Docker Desktop: Settings > Kubernetes > Enable Kubernetes
Rancher Desktop: Kubernetes is enabled by default

2. Verify kubectl can reach the cluster:

kubectl cluster-info

3. Deploy a backend service:

op run --env-file=1Password.env -- ./gradlew helmInstallToLocal

This builds the service, packages it as a Helm chart, and installs it into the local cluster. Helm values for local deployment live in helm/values-local.yaml within each backend repository.

4. Set up port forwarding as needed:

kubectl port-forward svc/operations 8080:8080

Verification Checklist

Run the following commands after setup to confirm each layer of the stack is working.

Backend:

cd ~/code/arda/operations
./gradlew build

A successful build produces no errors and runs all unit tests. Integration tests are excluded from the default build profile.

Frontend:

cd ~/code/arda/arda-frontend-app
npm install
npm run dev:mock

The development server starts on http://localhost:3000 with a mock API backend. No real backend services are required.

Documentation site:

cd ~/code/arda/documentation
npm install
make build

The site builds to dist/ without errors. Run make test-preview to catch link errors that are only visible under the production base path.

API tests:

cd ~/code/arda/api-test
npm install
op run --env-file=1Password/dev.env -- make test-dev

AI Agent Setup

Installing Claude Code

Claude Code is the primary AI coding assistant used at Arda. Install it as an npm global package:

npm install -g @anthropic/claude-code

Authenticate:

claude login

Workspace Configuration

The .claude symlink at the workspace root points to workspace/instructions/claude/. This directory contains:

agents/ — persona definitions loaded by the team-lead skill
skills/ — on-demand skill files (coding conventions, release workflows, etc.)
rules/ — always-on behavior rules applied to every session

When you start Claude Code from ~/code/arda/, it automatically picks up the workspace-level configuration and project-level CLAUDE.md. You do not need to configure anything manually.

Agent Behavior Conventions

Key conventions that Claude Code follows in this workspace:

Consultative by default. Claude Code produces explanations and plans unless you explicitly ask for file changes.
Concrete artifacts. When changes are requested, output is files — not conversational summaries.
Absolute paths only. When working across sibling repositories, all file operations use absolute paths to avoid operating on the wrong directory.
Secrets never in source. Claude Code is configured not to commit 1Password*.env files or any file containing API keys or credentials.

For AI-assisted multi-agent team workflows, see Working with AI Agent Assistants.

Development Workflows — Quick reference for build, test, and deploy commands.
Worktree Conventions — How to structure Git worktrees for project work.
Multi-Repository Gradle Development — Working across common-module and consuming services.
Working with AI Agent Assistants — Collaborating with Claude Code and multi-agent teams.