Getting started

This guide gets you from a fresh clone to a running stack you can develop against. Cluster operations (deploy, rollback, debugging) are documented separately in OPERATIONS.md.

Prerequisites

Tool	Minimum version	Used by
git	2.40+	Submodule workflows
make	4.x	Submodule helpers (root Makefile)
docker	24+	All service images
python	3.12	Every Python service (uv manages it)
uv	0.5+	Python dependency + venv management
node	22 LTS	Frontend builds
npm	10+	Frontend dependency management
helm	3.14+	Chart linting / templating
kubectl	1.30+	Cluster access
gcloud	latest	GKE auth + Secret Manager

Mobile development additionally needs Android Studio (Gradle 8.6 – 8.13) and / or Xcode (iOS 13+) — see the mobile app READMEs.

Clone + initialize

The parent repo holds every submodule pointer. Clone with submodules in one shot:

git clone --recurse-submodules \
  git@github.com:Cashless-Media/platform.git cashless
cd cashless

If you already cloned without --recurse-submodules, run:

make init

Other day-to-day helpers:

make sync       # Update all submodules to latest cashless-v2
make status     # Show each submodule's HEAD + branch
make dirty      # Show submodules with local changes
make branches   # Show current branch per submodule

Branching policy

This project is pre-launch. Until everything is implemented and deployed, we do not work with pull requests. Push commits directly to the active development branch in each repo:

• Parent monorepo + all submodules: cashless-v2.
• Do not create feat/* feature branches or open PRs for intermediate work.
• Do not split work across review rounds — land it and move on.

Once the platform launches, feature branches and PR reviews resume as the default.

Running a backend service locally

Each Python service uses uv and its own pyproject.toml. Example for cashless-backend:

cd backend/cashless-backend
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env
# Edit .env — point at a local MySQL + Redis
gunicorn -c gunicorn.conf.py app:app

personalaccount-api and cashless-auth follow the same shape; check each service's README for the exact entrypoint.

Do NOT run installs at the root

There is no root build system. npm install, pip install, and gradle build at the parent repo will fail. Always cd into the specific submodule first.

Running a frontend locally

cd frontend/cashless-admin-ui
npm install
npm run start              # Angular CLI dev server on :4200
npm test                   # Jest
npm run test:e2e           # Playwright (needs the dev server up)

All four web frontends (cashless-admin-ui, cashless-refund-ui, marketplace-user-ui, personalaccount-ui) share the same Angular 21 + ESLint 9 + Jest + Playwright shape on cashless-v2. The legacy Angular 7 versions on develop / master are not the integration target.

Building images

Every service image is built by GitHub Actions on push to cashless-v2, but you can reproduce a build locally:

# Backend example — build context is the parent repo root so submodules resolve
docker build \
  -f backend/cashless-backend/Dockerfile \
  -t cashless-backend:dev \
  .

Images push to ghcr.io/cashless-media/<service>:sha-<12 hex>. ArgoCD Image Updater detects new tags and writes them into deploy/argocd/values/<service>.yaml.

Connecting to the dev2 cluster

gcloud container clusters get-credentials cashless-dev2 \
  --region us-central1 --project cashless-media
kubectl --context cashless-dev2 -n cashless get pods

ArgoCD UI lives behind a port-forward:

kubectl --context cashless-dev2 -n argocd \
  port-forward svc/argocd-server 8080:80
# open http://localhost:8080

Grab the initial admin password from the argocd-initial-admin-secret Secret in the argocd namespace.

Where to look next

• Services — every public host and what runs behind it.
• API reference — Swagger / OpenAPI for every backend.
• Architecture — service boundaries, deploy flow, data layer.
• OPERATIONS.md — cluster bootstrap, deploy debugging, on-call runbook.
• Per-submodule CLAUDE.md — service-specific invariants and context.