How to Develop in the Front End

A developer-facing guide for working on the Arda frontend application (arda-frontend-app). Covers the development workflow, PR previews, the production deployment pipeline, manual redeploy/rollback, and local development.

Development Workflow

1. Create a feature branch off main
2. Make your changes and push to the branch
3. Open a PR against main (PRs can come from any branch — there is no branch promotion chain)
4. Amplify PR preview deploys automatically — a temporary preview URL appears as a comment on the PR (e.g., pr-42.d38w5m1ngjza76.amplifyapp.com). The preview uses the dev partition’s backend (same API Gateway, Cognito pools, database).
5. Verify your changes at the preview URL. Each push to the PR branch redeploys to the same URL.
6. CI runs on the PR: lint, build, unit tests. All must pass to merge.
7. Get reviewer approval and merge.
8. The production deployment pipeline takes over automatically (see below).

PR Preview Details

PR previews are enabled on the dev Amplify app and are managed entirely by Amplify — no GitHub Actions workflow is involved.

Property	Value
Trigger	Amplify webhook on PR open/push
Backend	Dev partition (dev.alpha002.io.arda.cards) — same API Gateway, Cognito pools, database as dev
URL pattern	pr-{N}.d38w5m1ngjza76.amplifyapp.com
Cleanup	Automatic on PR close/merge
Auth	Works with dev Cognito credentials — direct password auth (USER_PASSWORD_AUTH), no callback URL configuration needed

Notes:

• PR previews build independently of GitHub Actions CI. They trigger immediately on PR open/push via a GitHub webhook.
• Lint and e2e tests run only in GitHub Actions CI and gate the merge to main, not the preview.
• The preview URL is posted as a comment on the PR by Amplify.
• The preview inherits all of the dev app’s environment variables.

PR Preview Use Cases

Previews can be used in various scenarios:

• Quick turnaround in development as they only have the unit tests to run before deployment.
• Get early, interactive, close loop feedback from stakeholders during the implementation of a feature or bug fix.
• Have longer term feature or experimental branches for large refactors or big, complex features. In this case, the branch needs to be frequently rebased onto main or merged if it is important to keep it up to date with other changes.

CI/CD Deployment Pipeline

Pre-Merge Checks

Before a PR can be merged to main, all of the following must pass (enforced by branch ruleset):

Check	Workflow	What it verifies
lint	ci.yaml	npm run lint — code style and static analysis
build	ci.yaml	make build — Next.js production build succeeds
test	ci.yaml	make test — Jest unit tests pass
e2e	e2e.yaml	Playwright end-to-end tests (Chromium, mock mode)
validate-release	ci.yaml	CHANGELOG.md version bump matches change category via clq-action
Copilot code review	Ruleset	Automated code review
1 reviewer approval	Ruleset	At least one team member must approve

All checks run automatically on every push to the PR branch. The PR cannot be merged until all required checks pass and reviewer approval is obtained.

Note

The coverage check (coverage.yaml) also runs on PRs but is not required — it is informational only. It runs the full Jest + Playwright coverage pipeline and uploads a merged coverage report.

Post-Merge Deployment Pipeline

After a PR merges to main:

1. CI (ci.yaml) runs on the merge commit: lint, build, test, validate-release
2. On CI success, Deploy (deploy.yaml) triggers automatically via workflow_run
3. The deploy workflow pins the exact commit SHA that passed CI, so even if main advances before deploy starts, the verified commit is what gets deployed
4. Deployment proceeds sequentially through all partitions:

dev (automatic) → stage (reviewer approval) → demo (automatic) → prod (reviewer approval)

5. Each partition deployment:

   • Fetches configuration from purpose-configuration (aws_role, aws_region)
   • Derives the frontend IAM role ARN (appends FrontEnd to the service role name)
   • Assumes the role via OIDC — no AWS credentials stored in GitHub
   • Reads Amplify App ID and Branch Name from CloudFormation exports (all in us-east-1)
   • Calls aws amplify start-job --commit-id {sha} to trigger an Amplify build of that exact commit
   • Polls aws amplify get-job until the build succeeds or fails (15-minute timeout)
   • Amplify handles the actual build (npm ci, env var resolution, npm run build) and deployment

6. Authorization gates: stage and prod require approval from a reviewer (denisa, jmpicnic, danmerb, davequinta). The workflow pauses and sends a GitHub notification. Approve in the GitHub Actions UI.

7. If any partition fails, the chain stops — subsequent partitions are not deployed. Fix the issue and re-trigger via workflow_dispatch.

No secrets flow through GitHub Actions. The workflow only has Amplify API permissions (StartJob, GetJob) and cloudformation:ListExports. All environment variables and secrets are resolved by Amplify at build time from CloudFormation exports and Secrets Manager.

Manual Redeploy / Rollback

To deploy a specific commit to a single partition:

1. Go to: https://github.com/Arda-cards/arda-frontend-app/actions/workflows/redeploy.yaml
2. Click “Run workflow”
3. Select main branch
4. Choose the target partition (dev, stage, demo, prod)
5. Enter the commit SHA (full 40-character SHA — find via git log --oneline main)
6. Run the workflow

The workflow verifies CI passed for that commit before deploying. It checks only CI-relevant check runs (lint, build, test, validate-release) — deploy workflow status and coverage are excluded. If CI failed or never ran for that commit, the redeploy is blocked.

Emergency rollback (bypasses GitHub Actions — use only if the workflow itself is broken):

Partition	Re-enable auto-build	Trigger manual build
dev	aws amplify update-branch --app-id d38w5m1ngjza76 --branch-name dev --enable-auto-build --region us-east-1	aws amplify start-job --app-id d38w5m1ngjza76 --branch-name dev --job-type RELEASE --region us-east-1
stage	aws amplify update-branch --app-id d1kbrvra79y8sc --branch-name stage --enable-auto-build --region us-east-1	aws amplify start-job --app-id d1kbrvra79y8sc --branch-name stage --job-type RELEASE --region us-east-1
demo	Use redeploy.yaml with a known-good SHA
prod	aws amplify update-branch --app-id duhexavnwh88g --branch-name main --enable-auto-build --region us-east-2	aws amplify start-job --app-id duhexavnwh88g --branch-name main --job-type RELEASE --region us-east-2

Note: prod Amplify is in us-east-2 (all others are us-east-1).

Manual Full Deploy

To trigger a full sequential deployment without waiting for a PR merge:

1. Go to: https://github.com/Arda-cards/arda-frontend-app/actions/workflows/deploy.yaml
2. Click “Run workflow”
3. Select main branch
4. Run the workflow

This deploys the latest main commit to all four partitions sequentially with the same approval gates.

Local Development

Standard Next.js local development:

cd arda-frontend-app
npm install
npm run dev

Configure environment variables in .env.local for local development. The application requires:

• NEXT_PUBLIC_COGNITO_* — Cognito configuration (user pool, client ID, region)
• NEXT_PUBLIC_API_URL — Backend API base URL
• BASE_URL — Server-side backend URL
• ARDA_API_KEY — API authentication key

See the .env.example file or the dev partition’s Amplify environment variables for reference values.

Environment Map

Partition	URL	Account	Region	Backend API	Purpose
dev	dev.alpha002.app.arda.cards	Alpha002 (139852620346)	us-east-1	dev.alpha002.io.arda.cards	Development testing, PR preview backend
stage	stage.alpha002.app.arda.cards	Alpha002 (139852620346)	us-east-1	stage.alpha002.io.arda.cards	Pre-production staging
demo	demo.alpha001.app.arda.cards	Alpha001 (009765408297)	us-east-1	demo.alpha001.io.arda.cards	Demo environment
prod	live.app.arda.cards	Alpha001 (009765408297)	us-east-2	prod.alpha001.io.arda.cards	Production

GitHub Actions Workflows

Workflow	Trigger	Purpose
ci.yaml	Push, PR	Lint, build, test, validate-release. Gates merge to main.
deploy.yaml	workflow_run on CI success on main (+ manual workflow_dispatch)	Sequential deployment to dev → stage → demo → prod with approval gates. Pins the CI-verified commit SHA.
redeploy.yaml	workflow_dispatch (partition + SHA)	Targeted single-partition redeploy or rollback. Verifies CI passed before deploying.
reusable_deployment.yaml	Called by deploy/redeploy	Shared deployment logic: purpose-config → OIDC → CloudFormation exports → StartJob → poll.
coverage.yaml	PR	Full coverage pipeline (Jest + Playwright). Informational — does not gate merge.

Key Architecture Decisions

• Amplify remains the build and hosting platform — GitHub Actions only orchestrates when to build, not how. No secrets or env vars pass through GitHub Actions.
• All partitions build from main — the same commit is deployed to all four environments. Environment-specific configuration is resolved by Amplify from CloudFormation exports and Secrets Manager.
• Sequential deployment with gates — dev deploys first (canary), stage and prod require human approval. If dev fails, nothing else deploys.
• Commit pinning — the workflow_run trigger passes the exact CI-verified commit SHA to all partitions, preventing race conditions if main advances.