[general] Add docker-compose for unified local development (Part 3)

.commitlintrc.json

@@ -0,0 +1,15 @@
+{
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "type-enum": [
+      2,
+      "always",
+      ["feat", "fix", "docs", "test", "chore", "refactor", "ci", "build", "perf", "revert"]
+    ],
+    "scope-case": [2, "always", "lower-case"],
+    "subject-case": [2, "never", ["sentence-case", "start-case", "pascal-case", "upper-case"]],
+    "subject-empty": [2, "never"],
+    "subject-full-stop": [2, "never", "."],
+    "header-max-length": [2, "always", 100]
+  }
+}

.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+.git
+.gitignore
+.next
+dist
+build
+coverage
+*.log
+.env
+.env.local
+stellar_card.db
+*.sqlite

.env.docker.example

@@ -0,0 +1,86 @@
+# =============================================================================
+# Stellar Card Docker Compose Environment Variables
+# Copy to .env and fill in values. Never commit .env to version control.
+# =============================================================================
+
+# =============================================================================
+# Backend Configuration
+# =============================================================================
+# Server port
+PORT=4000
+
+# Node environment
+NODE_ENV=development
+
+# Database path (SQLite default)
+DB_PATH=/app/data/stellar_card.db
+
+# =============================================================================
+# Stellar Configuration
+# =============================================================================
+# Stellar network: testnet or mainnet
+STELLAR_NETWORK=testnet
+
+# USDC issuer address
+STELLAR_USDC_ISSUER=GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN
+
+# Treasury secret key (generate with: soroban key generate)
+# WARNING: Never commit real secret keys
+STELLAR_XLM_SECRET=
+
+# Soroban receiver contract ID
+RECEIVER_CONTRACT_ID=
+
+# =============================================================================
+# VCC Fulfillment Service
+# =============================================================================
+VCC_API_BASE=https://vcc.ctx.com
+CARDS402_BASE_URL=http://localhost:4000
+
+# Secret for verifying HMAC-signed callbacks from VCC
+# Generate with: openssl rand -hex 32
+VCC_CALLBACK_SECRET=
+
+# =============================================================================
+# Frontend Configuration
+# =============================================================================
+NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
+NEXT_PUBLIC_STELLAR_NETWORK=testnet
+
+# =============================================================================
+# PostgreSQL Configuration (Optional - when using --profile db)
+# =============================================================================
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_USER=stellar_card
+POSTGRES_PASSWORD=stellar_card_dev
+POSTGRES_DB=stellar_card
+
+# =============================================================================
+# Redis Configuration (Optional - when using --profile db)
+# =============================================================================
+REDIS_HOST=redis
+REDIS_PORT=6379
+
+# =============================================================================
+# CORS Configuration
+# =============================================================================
+# Comma-separated allowed origins for the agent API
+CORS_ORIGINS=http://localhost:3000
+
+# =============================================================================
+# Internal Dashboard Access
+# =============================================================================
+# Comma-separated emails allowed to access /internal/* routes
+# INTERNAL_EMAILS=ops@example.com,eng@example.com
+
+# =============================================================================
+# Error Tracking (Optional)
+# =============================================================================
+# SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
+
+# =============================================================================
+# Development Settings
+# =============================================================================
+# SDK development - allow insecure base URL for local testing
+CARDS402_ALLOW_INSECURE_BASE_URL=1

.github/CICD.md

@@ -23,6 +23,12 @@ Jobs:
 
 - **type-matrix**: Tests TypeScript compatibility with multiple versions (5.0 - 5.3)
 
+### 1a. E2E Tests (`e2e.yml`)
+
+Runs the Playwright suite in `stellar_card-frontend/e2e/` across a CI matrix covering `chromium`, `firefox`, `webkit`, `Mobile Chrome`, and `Mobile Safari` — mirroring every project defined in `playwright.config.ts` except `Microsoft Edge`, which needs a system-installed Edge browser that isn't available on the `ubuntu-latest` runner image and is left as a local-only / self-hosted-runner project.
+
+`Mobile Chrome` and `Mobile Safari` are device-emulation presets, not separate browser engines — they render on `chromium` and `webkit` respectively, so the workflow resolves each matrix entry to its underlying engine before installing or caching browser binaries.
+
 ### 2. Security Audit (`security.yml`)
 
 Runs:
@@ -156,6 +162,22 @@ Add to README:
 2. Check `.github/dependabot.yml` syntax
 3. Verify package manager is detected (run actions manually)
 
+## Caching Strategy
+
+All workflows cache dependencies and build artifacts to keep CI fast:
+
+| Workflow | Cache | Key basis |
+|----------|-------|-----------|
+| `test.yml`, `a11y.yml` | npm store + Node modules (via `.github/actions/setup-node`) | OS, Node version, `package-lock.json` hash |
+| `test.yml` | TypeScript `.tsbuildinfo` | OS, Node version, `src/**` + `tsconfig*.json` hash |
+| `e2e.yml`, `a11y.yml` | Playwright browser binaries (`~/.cache/ms-playwright`) | OS, installed `@playwright/test` version, matrix project |
+| `sdk-validate.yml`, `publish.yml`, `release.yml` | npm store (via `actions/setup-node@v4` `cache: npm`) | `package-lock.json` hash |
+| `security.yml` | npm store (via `actions/setup-node@v4` `cache: npm`) | `package-lock.json` hash per audited directory |
+
+Playwright caches are keyed per browser project so each matrix job (`chromium`, `firefox`, `webkit`) only restores its own binaries — a cache hit still runs `playwright install-deps` to pull OS-level shared libraries, which don't persist inside the cached path.
+
+Use the reusable `.github/actions/setup-node` composite action for any new workflow that runs `npm ci` — it wires up both the npm store cache and `actions/setup-node`'s built-in lockfile cache with a consistent key format.
+
 ## Best Practices
 
 1. **Always run tests locally before pushing**

.github/actions/setup-node-project/README.md

@@ -0,0 +1,8 @@
+# Setup Node project action
+
+This composite action centralizes Node setup and caching for repository
+workflows. The npm download cache is keyed by the selected lockfile, while
+reusable tool output is isolated by operating system, Node version, an
+explicit cache schema version, and the lockfile hash.
+
+Increment `cache-version` after changing the cached directory layout.

.github/actions/setup-node-project/action.yml

@@ -0,0 +1,35 @@
+name: Setup Node project
+description: Configure Node and restore deterministic npm and build caches
+
+inputs:
+  node-version:
+    description: Node.js version
+    required: true
+  working-directory:
+    description: Project directory containing package-lock.json
+    required: true
+  cache-version:
+    description: Increment to invalidate build caches
+    default: v1
+
+runs:
+  using: composite
+  steps:
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: npm
+        cache-dependency-path: ${{ inputs.working-directory }}/package-lock.json
+
+    - name: Restore project build cache
+      uses: actions/cache@v4
+      with:
+        path: |
+          ${{ inputs.working-directory }}/.eslintcache
+          ${{ inputs.working-directory }}/.next/cache
+          ${{ inputs.working-directory }}/node_modules/.cache
+          ${{ inputs.working-directory }}/*.tsbuildinfo
+        key: node-build-${{ runner.os }}-${{ inputs.node-version }}-${{ inputs.cache-version }}-${{ hashFiles(format('{0}/package-lock.json', inputs.working-directory)) }}
+        restore-keys: |
+          node-build-${{ runner.os }}-${{ inputs.node-version }}-${{ inputs.cache-version }}-

.github/actions/setup-node/action.yml

@@ -0,0 +1,32 @@
+name: Setup Node.js with caching
+
+description: |
+  Composite action that sets up Node.js with optimized caching.
+  Reusable across all workflows to keep cache keys consistent.
+
+inputs:
+  node-version:
+    description: 'Node.js version to use'
+    default: '20.x'
+  working-directory:
+    description: 'Directory containing package-lock.json'
+    default: '.'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Setup Node.js ${{ inputs.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ inputs.node-version }}
+        cache: npm
+        cache-dependency-path: '${{ inputs.working-directory }}/package-lock.json'
+
+    - name: Cache npm store
+      uses: actions/cache@v4
+      with:
+        path: ~/.npm
+        key: npm-${{ runner.os }}-node${{ inputs.node-version }}-${{ hashFiles(format('{0}/package-lock.json', inputs.working-directory)) }}
+        restore-keys: |
+          npm-${{ runner.os }}-node${{ inputs.node-version }}-
+          npm-${{ runner.os }}-