shd.build/README.md

SHD.build

A SvelteKit community application for The Division Resurgence. SHD.build combines a public game database, loadout builder, shared builds, guides, account management, and the ISAC data-management console.

See docs/architecture.md for the implementation model.

Database

The server uses the in-process @tursodatabase/database package and a local SQLite-compatible file. Turso Cloud is not required.

Create or update the local database:

npm run db:migrate

The Infisical dev environment sets the local file to ./data/shd-build-development.db.

Store custom avatars as metadata-free 256 × 256 WebP files. Set TDR_AVATAR_STORAGE_PATH to a persistent, writable directory in production; it defaults to data/avatars. The same configuration works on Windows and Linux.

Seed the initial local accounts once:

npm run db:seed-users

The seed creates Aewyn and Quartermaster with the standard user role. It generates and displays strong temporary passwords once, then stores only salted Argon2id hashes. DEFAULT_ADMIN_PASSWORD is the password variable name for Aewyn; it does not grant administrator authority.

Sign-in never grants administrator authority automatically. For local development, give the target account a verified email, enroll TOTP at /account/security, and save its one-time recovery codes. Stop the development server, then run:

npm run admin:bootstrap -- <verified-email>

The offline command requires an active TOTP factor and an unused recovery code, revokes the target account's sessions, and refuses to run when an active full administrator already exists. Restart the development server after it succeeds. See docs/DEPLOYMENT.md for staging and production operation.

Develop

npm run dev

Infisical secrets

The committed .infisical.json connects the project to the self-hosted Infisical instance at https://secrets.jb.codes. Authenticate the local CLI once. The CLI uses its configured system vault and can fall back to an encrypted file vault when the operating-system keyring is unavailable.

npx infisical login --domain=https://secrets.jb.codes
npm run dev

Local commands use the dev environment. Application configuration lives under /app; the scheduler bearer token lives under /shared/scheduler. Staging and production commands select the staging and prod environments explicitly. npm run check, npm test, and npm run build do not contact Infisical.

Staging and production containers authenticate at startup with separate Universal Auth identities. Gitea stores each client secret, while repository variables hold the matching non-secret client IDs. The containers fetch current values before migration or startup and stop if authentication or validation fails.

Containers and staging deployment

The application uses the official SvelteKit Node adapter and a multi-stage Dockerfile. Keep database files, database backups, user avatars, and uploaded game-data icons under /app/data on a persistent volume. Inject runtime secrets when the container starts; keep them out of the image.

docs/DEPLOYMENT.md documents the staging and production Compose topologies. A push to main triggers both deployment workflows. Each workflow validates Infisical access and the candidate image while the current service stays online, then stops its application and scheduler for backup and migration.

Passwordless authentication

Use passkeys as the preferred sign-in method. Set APP_ORIGIN to the exact public origin for registration and authentication. Set PASSKEY_RP_ID to that hostname or a registrable parent domain. Hosted environments use shd.build, which permits credentials on shd.build, stage.shd.build, and dev.shd.build. Use localhost for direct local development.

Magic links require SMTP_HOST and SMTP_FROM. SMTP_PORT defaults to 587. Set SMTP_SECURE=true for implicit TLS, normally on port 465; the default false uses STARTTLS. If the SMTP server requires authentication, set both SMTP_USER and SMTP_PASSWORD. An account owner activates an email identity by following a 15-minute, single-use verification link.

Validate

npm run check
npm run build

The shared visual language and dashboard conventions are documented in docs/DESIGN_SYSTEM.md.

Empirically derived weapon and gear level-range calculations, rounding rules, validation boundaries, and regression observations are documented in docs/STAT_LEVEL_SCALING.md.