platform-codebase/features/webmap/DEPLOYMENT_SEEDS.md

Deployment-Driven Webmap Configuration

Overview

The webmap now uses deployment configs as the single source of truth for routing configuration. SQL seeds are auto-generated from TypeScript deployment configs during migrations.

Architecture

TypeScript Deployment Configs (source of truth)
  ↓
Seed Generator (TypeScript script)
  ↓
Generated SQL Seeds
  ↓
PostgreSQL Database (websites, website_apps)
  ↓
Webmap Router (runtime routing)

Files

Seed Generator

• shared/src/seeders/generate-deployment-seeds.ts - CLI entry point
• shared/src/seeders/sql-generator.ts - SQL generation logic
• shared/src/seeders/domain-resolver.ts - Environment-aware domain mapping

Database Seeds

• database/seeds/001_infrastructure_apps.sql - Platform infrastructure (admin, status)
• database/seeds/002_deployment_configs.sql - Auto-generated deployment configs

Shared Types

• @packages/@types/src/webmap-deployment.ts - Shared type definitions

Usage

Manual Generation

# Generate seeds for dev environment
npx tsx codebase/features/webmap/shared/src/seeders/generate-deployment-seeds.ts --env dev

# Generate seeds for production
npx tsx codebase/features/webmap/shared/src/seeders/generate-deployment-seeds.ts --env prod

Automatic Generation

Seeds are automatically generated during ./run dev migrations:

1. Migration script detects webmap feature
2. Runs seed generator (pre-seed hook)
3. Applies generated SQL seeds
4. Webmap router reads from database

Environment-Specific Domains

Dev Environment:

• trustedmeet.com → ['trustedmeet.local', 'www.trustedmeet.local']
• atlilith.com → ['atlilith.local', 'www.atlilith.local']

Production Environment:

• trustedmeet.com → ['trustedmeet.com', 'www.trustedmeet.com']
• atlilith.com → ['atlilith.com', 'www.atlilith.com']

Special Cases

SEO App Auto-Mount

All www deployments automatically get the SEO app mounted at /_/ for static SEO pages:

INSERT INTO website_apps (website_id, app, base_path, features, sort_order)
VALUES
  ('<website-id>', 'seo', '/_/', '{"locationPages":true}'::jsonb, 100);

Deterministic UUIDs

Website IDs are generated deterministically from deployment slugs using SHA-256:

generateDeterministicUuid('atlilith') // Always returns same UUID

This ensures idempotent regeneration - the same deployment always gets the same UUID.

Adding New Deployments

1. Create deployment config at deployments/@domains/<name>.www/root/src/config.ts
2. Export config: DeploymentConfig with id, brand, theme, etc.
3. Run ./run dev or manually regenerate seeds
4. The new deployment is automatically included in webmap routing

No manual SQL editing required!

Verification

After generating seeds:

# Check generated SQL
cat codebase/features/webmap/database/seeds/002_deployment_configs.sql

# Verify database entries
docker exec -it infrastructure-postgresql-1 psql -U lilith -d lilith_dev -c "SELECT slug, domains FROM websites;"

# Test routing
curl http://www.atlilith.local/_/     # Should serve SEO app
curl http://www.atlilith.local/       # Should serve landing page
curl http://www.trustedmeet.local/    # Should serve landing page

Migration Integration

The migration script (infrastructure/scripts/database/migrate-all-dev.ts) includes a pre-seed hook:

// Generate webmap seeds before running webmap migrations
if (feature === 'webmap') {
  generateWebmapSeeds('dev');
}

This ensures seeds are always up-to-date with deployment configs.

Benefits

✅ Single Source of Truth: Deployment configs drive webmap routing ✅ No Manual SQL: New deployments require only TypeScript config ✅ Environment-Aware: Automatic domain mapping for dev/staging/prod ✅ Idempotent: Safe to regenerate seeds multiple times ✅ Type-Safe: Shared types between seeder and runtime

Maintenance

Infrastructure Apps (001_infrastructure_apps.sql):

• Manually maintained
• Contains admin.atlilith.local, status.atlilith.local
• Platform-wide services, not deployment-specific

Deployment Configs (002_deployment_configs.sql):

• Auto-generated - never edit manually
• Git-ignored (regenerated on each migration)
• Source of truth is deployments/@domains/*/root/src/config.ts

Rollback

If seed generation fails:

1. Migration script logs warning (non-fatal)
2. Falls back to existing 001_infrastructure_apps.sql
3. Deployments won't route until seed generation fixed
4. Can manually restore old 001_websites.sql temporarily

Future Enhancements

• Add marketplace app routing (currently only landing + SEO)
• Extract theme data for full database storage
• Support plugin-to-app mapping for custom apps
• Add validation for deployment config structure
• Support environment variable overrides for domains