---
name: deploying-dev-orchard-spas
description: Guides deployment and provisioning of The Orchard internal SPA/frontend apps on dev.theorchard.io. Use when creating, reviewing, or troubleshooting Terraform internal_spa infrastructure, S3 static frontend deploy scripts, Vite/Suite frontend builds, hashed asset uploads, or app-specific data file publishing for dev.theorchard.io apps.
---

# Deploying dev.theorchard.io internal SPAs

Use this skill for The Orchard internal static frontend apps hosted as `*.dev.theorchard.io` with Terraform `terraform-internal-spa` infrastructure and S3 asset uploads.

## Load-on-demand references

- Read `references/dev-internal-spa.md` when provisioning Terraform, writing deploy scripts, or checking identity-analysis conventions.
- Read `templates/deploy-internal-spa.sh` only when the task asks for a reusable shell script/template.

## Default workflow

1. Identify the app name, service name, domain, build output directory, asset naming pattern, and package manager from the repo.
2. Verify infrastructure exists or is planned with `terraform-internal-spa` for `service_name.dev.theorchard.io`.
3. Build with the app's normal frontend command and required env vars (`CDN_URL`, `VITE_API_BASE_URL`, GraphQL/Auth/Sentry/Datadog vars if the app needs them).
4. Upload `index.html` to the S3 bucket root for the app domain.
5. Upload hashed JS/CSS/worker assets under the app asset prefix, usually the Suite `appName`.
6. For data-backed static apps, upload versioned data files first, then build with the selected data filename in the frontend env.
7. Check the final URL and avoid adding cache invalidation or public access changes unless the target app's Terraform/module requires them.

## Guardrails

- Do not hard-code secrets or credentials in Terraform, deploy scripts, or `.env` files.
- Prefer existing repo scripts and naming conventions over inventing a new deployment shape.
- Keep `index.html` at the bucket root unless the app has a documented subpath entrypoint.
- Keep hashed assets under a stable prefix to avoid root namespace collisions across files.
- Confirm AWS account/role and bucket target before upload commands that mutate S3.
- If adapting identity-analysis, preserve the two-step data flow: upload `combined_users_*.json.gz` to `data/`, then build/deploy with `VITE_DATA_FILE`.

## Identity-analysis baseline

Known reference implementation:

- App repo path: `ratoui/identity-analysis`
- Publish script: `ratoui/identity-analysis/scripts/publish-data.sh`
- Frontend deploy script: `ratoui/identity-analysis/frontend/scripts/deploy.sh`
- Terraform path: `theorchard/terraform-infra/dev/identity-analysis`
- Domain and S3 bucket: `identity-analysis.dev.theorchard.io`
- Asset prefix/app name: `frontend-identity-analysis`
- Data prefix: `data/`