Multi-Environment Setup

This document describes Juniro's multi-environment architecture with Development and Production environments, using branch-based deployment.

Overview

Environment	Branch	Purpose
Development	develop	Testing, integration, pre-release validation
Production	main	Live customer-facing services
Preview	PR branches	Ephemeral deployments for code review

Architecture

                     juniro-design
                    ┌─────┴─────┐
                 develop      main
                    │           │
    ┌───────────────┼───────────┼───────────────┐
    ▼               ▼           ▼               ▼
web-public    web-parents  web-providers   web-admin
(develop/main) (develop/main) (develop/main) (develop/main)
    │               │           │               │
    ▼               ▼           ▼               ▼
┌─────────────────────────────────────────────────────┐
│                      Vercel                         │
│  develop branches → dev.juniro.com (Dev)           │
│  main branches → juniro.com (Prod)                 │
└─────────────────────────────────────────────────────┘
                         │
            ┌────────────┴────────────┐
            ▼                         ▼
    ┌───────────────┐         ┌───────────────┐
    │ Supabase DEV  │         │ Supabase PROD │
    │ (juniro-dev)  │         │ (juniro-prod) │
    └───────────────┘         └───────────────┘

URLs

Service	Development	Production
Public Site	dev.juniro.com	juniro.com
Parents Portal	dev-parents.juniro.com	parents.juniro.com
Providers Portal	dev-providers.juniro.com	providers.juniro.com
Admin Portal	dev-admin.juniro.com	admin.juniro.com
API	dev-api.juniro.com	api.juniro.com
Supabase	juniro-dev project	juniro-prod project

Branching Strategy

Git Flow (Simplified)

Branch	Purpose	Deploys To
main	Production-ready code	Production
develop	Integration branch	Development
feature/*	Feature development	Preview (PR-based)
hotfix/*	Production fixes	Preview → Production

Branch Protection

main branch:

• Require pull request reviews (1+ approvals)
• Require status checks to pass
• Block force pushes
• Restrict direct push to admins only

develop branch:

• Require status checks to pass
• Allow CI/CD direct push
• Block force pushes

Deployment Flow

Developer workflow:

1. Create feature branch from develop
   └── git checkout -b feature/my-feature develop

2. Make changes, push
   └── Triggers: PR preview deployment (*.vercel.app)

3. Merge to develop (after review)
   └── Triggers: Auto-deploy to Dev environment

4. Test in Dev environment
   └── Verify at dev.juniro.com, dev-parents.juniro.com, etc.

5. Merge develop to main (release)
   └── Triggers: Auto-deploy to Production

Environment Configuration

Vercel Settings

For each web app, configure in Vercel Dashboard:

Project Settings → Git:

• Production Branch: main
• Preview deployments: enabled

Project Settings → Domains:

• Assign develop branch → dev-*.juniro.com
• Assign main branch → production domains

Project Settings → Environment Variables:

Variable	Development	Production
NEXT_PUBLIC_API_URL	https://dev-api.juniro.com	https://api.juniro.com
NEXT_PUBLIC_SUPABASE_URL	(dev project URL)	(prod project URL)
NEXT_PUBLIC_SUPABASE_ANON_KEY	(dev anon key)	(prod anon key)
NEXT_PUBLIC_APP_ENV	development	production

Supabase Projects

Project	Purpose	Access
juniro-dev	Development database	Dev team
juniro-prod	Production database	Restricted

Dev database features:

• Seed data for testing
• Safe to reset/modify
• No real user data

Prod database features:

• Real user data
• Daily backups
• Restricted access

CI/CD Workflows

Design System Sync

Design system changes flow through:

juniro-design (develop) → Sync → web-apps (develop) → Deploy → Dev
juniro-design (main)    → Sync → web-apps (main)    → Deploy → Prod

Workflow files (in juniro-infra):

• sync-design-to-public-portal.yml
• sync-design-to-parent-portal.yml
• sync-design-to-provider-portal.yml
• sync-design-to-admin-portal.yml

Workflow Inputs

All sync workflows accept:

inputs:
  target_branch:
    description: 'Target branch (develop/main)'
    default: 'develop'
    options: [develop, main]
  source_branch:
    description: 'Source branch from juniro-design'
    default: 'develop'
    options: [develop, main]
  dry_run:
    description: 'Preview changes without committing'
    default: 'true'

Local Development

Sync Scripts

Local sync scripts support branch targeting:

# Sync to develop branch (default)
./scripts/sync-local-public.sh

# Sync to specific branch
./scripts/sync-local-public.sh develop
./scripts/sync-local-public.sh main

# Sync all repos to develop
./scripts/sync-all-to-dev.sh

Environment Variables (Local)

Create .env.local in each web app:

# For local development pointing to dev backend
NEXT_PUBLIC_API_URL=https://dev-api.juniro.com
NEXT_PUBLIC_SUPABASE_URL=https://xxx.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=xxx
NEXT_PUBLIC_APP_ENV=development

GitHub Secrets

Repository Secrets (juniro-infra)

Secret	Purpose
COMPONENT_SYNC_PAT	Cross-repo access for sync
VERCEL_TOKEN	Vercel deployments
VERCEL_ORG_ID	Vercel organization

Environment-Scoped Secrets

Use GitHub Environments for per-environment secrets:

development environment:

• SUPABASE_URL (dev)
• SUPABASE_ANON_KEY (dev)

production environment:

• SUPABASE_URL (prod)
• SUPABASE_ANON_KEY (prod)
• Required reviewers for deployment

Costs

Service	Monthly Cost
Supabase Dev (Free/Pro)	$0-25
Vercel (existing plan)	$0 additional
DNS (subdomains)	$0
Total	~$0-25/mo

Future: Adding Staging

When ready to add a staging environment:

1. Create staging branch in each repo
2. Add staging.juniro.com domains in Vercel
3. Create juniro-staging Supabase project
4. Update workflows for 3 environments
5. Add staging environment to GitHub Environments

Future flow:
develop → Development (testing)
staging → Staging (pre-prod validation)
main → Production (live)

Troubleshooting

Common Issues

Deployment not triggering:

• Verify branch name matches exactly (develop not dev)
• Check GitHub Actions logs for errors
• Verify Vercel project settings

Wrong environment variables:

• Check Vercel Environment Variables scoping
• Verify branch → environment mapping
• Check .env.local for local development

Design system not syncing:

• Run ./scripts/sync-local-*.sh locally first
• Check sync workflow logs
• Verify COMPONENT_SYNC_PAT has repo access

Rollback Procedures

Web App Rollback:

# Via Vercel CLI
vercel rollback [deployment-url]

# Via Git (revert commit)
git revert HEAD
git push origin main  # or develop

Database Rollback:

• Supabase Dashboard → Backups → Restore
• Use point-in-time recovery for recent issues

References

• Repository Architecture Strategy
• Git Workflow Guide
• API Architecture
• Vercel Documentation
• Supabase Documentation