New Customer Onboarding (Package-Based Architecture)

This guide outlines the streamlined process for onboarding new enterprise customers using the package-based architecture, replacing the legacy fork-based approach.

Prerequisites

Decisions:
- Domain name (SERVER_DOMAIN, PREVIEW_DOMAIN, and HOSTED_ZONE if DNS zone is different than SERVER_DOMAIN) (Customer)
- Will AWS be managing the service certificates? (Recommended) (Customer)
- Allocate a VPC to run the service (one per AWS account), and set any security groups for reaching that VPC (Customer)
- If service can't be on internet, SST changes may be required (Bike4Mind)
- Support email address (Customer)
- Mail from address (Customer)
- Where to run MongoDB or DocumentDB (Customer)

Package Setup (Replaces Fork Process)

Access to Private NPM Registry (Coordinated)
- Bike4Mind provides NPM organization access credentials (Bike4Mind)
- Customer configures NPM registry access: npm config set @bike4mind:registry https://registry.npmjs.org (Customer)
- Customer authenticates: npm login --scope=@bike4mind (Customer)
Create Customer Repository (Customer)
- Create new repository within customer org: customer-bike4mind (Customer)
- Initialize with package.json containing:
```
{
  "name": "customer-bike4mind",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "@bike4mind/core": "^1.0.0",
    "@bike4mind/client": "^1.0.0"
  }
}
```
- Run npm install to fetch packages (Customer)
- Commit initial package setup (Customer)

AWS Infrastructure Setup

Deployment Configuration

Secrets Configuration

Initial Build and Deploy

Local SST build to update zone list (Customer)
- SERVER_DOMAIN=$server_domain HOSTED_ZONE=$hosted_zone VPC_ID=$vpc_id pnpm sst build --profile $aws_profile --region $aws_region --stage dev
- Review and commit any necessary cdk.context.json changes
Deploy from Seed (Customer)
- Push configuration to repository
- Trigger deployment in Seed
- Monitor deployment progress
- Verify application is accessible at configured domain

Package Updates

With the package-based architecture, updates are streamlined:

Receive update notification from Bike4Mind

Update package versions in package.json:

{
  "dependencies": {
    "@bike4mind/core": "^1.1.0",
    "@bike4mind/client": "^1.1.0"
  }
}

Run npm install to fetch updates
Test in development environment
Deploy through Seed CI/CD pipeline

Advantages Over Fork-Based Approach

No submodule management: Eliminates daily submodule pointer updates
Simplified updates: Standard NPM package versioning
Better isolation: Clear separation between customer code and Bike4Mind packages
Easier rollbacks: Use NPM version pinning for stability
Cleaner repository: Customer repository contains only customizations
Database flexibility: Native support for both MongoDB and DocumentDB

Support and Maintenance

Package updates are published to the private NPM registry
Version compatibility is maintained through semantic versioning
Breaking changes are communicated in advance
Customer customizations remain isolated in their repository
Full source code transparency maintained through package access

Prerequisites​

Package Setup (Replaces Fork Process)​

AWS Infrastructure Setup​

Deployment Configuration​

Secrets Configuration​

Initial Build and Deploy​

Package Updates​

Advantages Over Fork-Based Approach​

Support and Maintenance​