shd.build/README.md

SHD.build

A SvelteKit application for creating and sharing loadouts for The Division Resurgence.

The first increment includes a responsive discovery page, an anonymous builder draft saved to local storage, authentication UI boundaries, an admin data-management preview, and an embedded Turso database foundation. See docs/architecture.md for the staged implementation plan.

Database

The server uses the in-process @tursodatabase/database package with a local SQLite-compatible file—there is no Turso Cloud dependency.

Create or update the local database:

npm run db:migrate

The default file is data/shd-build.db. Copy .env.example to .env to override its location.

Custom avatars are stored 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

This creates administrator Aewyn and standard user Quartermaster. Strong temporary passwords are generated and displayed once; only salted Argon2id hashes are stored.

Develop

npm run dev

Encrypted environment files

Development and production settings live in the committed, encrypted .env.development and .env.production files. Private decryption keys live only in the ignored .env.keys file; back it up in a password manager.

npm run env:decrypt              # decrypt both files for editing
npm run env:encrypt              # encrypt both files again
npm run env:stage                # encrypt and git-add both files
npm run env:decrypt:development  # operate on one environment
npm run env:decrypt:production

The repository pre-commit hook runs env:stage, so a commit always replaces staged plaintext environment files with encrypted versions. Git does not expose a pre-add hook, so use npm run env:stage instead of directly adding these two files when possible.

Never commit or lose .env.keys. Production should receive DOTENV_PRIVATE_KEY_PRODUCTION through its secret manager rather than copying the keys file onto the server.

Passwordless authentication

Passkeys are the preferred sign-in method. APP_ORIGIN must exactly match the public origin used for registration and authentication, while PASSKEY_RP_ID must be that hostname or a registrable parent domain. The hosted environments use shd.build, allowing credentials on both shd.build and dev.shd.build. Direct localhost development should use localhost.

Magic links require SMTP_HOST, SMTP_PORT, SMTP_SECURE, SMTP_USER, SMTP_PASSWORD, and SMTP_FROM. Port 465 normally uses SMTP_SECURE=true; port 587 normally uses false and upgrades with STARTTLS. Email identities become usable only after the account owner follows a 15-minute, single-use verification link.

Validate

npm run check
npm run build

Everything you need to build a Svelte project, powered by sv.

Creating a project

If you're seeing this, you've probably already done this step. Congrats!

# create a new project
npx sv create my-app

To recreate this project with the same configuration:

# recreate this project
npx sv@0.16.5 create --template minimal --types ts --install npm .

Developing

Once you've created a project and installed dependencies with npm install (or pnpm install or yarn), start a development server:

npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open

Building

To create a production version of your app:

npm run build

You can preview the production build with npm run preview.

To deploy your app, you may need to install an adapter for your target environment. 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.