# 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:

```sh
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:

```sh
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

```sh
npm run dev
```

## Encrypted environment files

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

```sh
npm run env:decrypt              # decrypt all environment files for editing
npm run env:encrypt              # encrypt all environment files again
npm run env:stage                # encrypt and git-add all environment files
npm run env:decrypt:development  # operate on one environment
npm run env:decrypt:staging
npm run env:decrypt:production
npm run env:sync:staging-credentials # copy shared Discord/SMTP values from development
```

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.

## Containers and staging deployment

The application uses the official SvelteKit Node adapter and includes a
multi-stage `Dockerfile`. Database files, database backups, user avatars, and
uploaded game-data icons live under `/app/data`, which must be a persistent
volume. Runtime secrets are injected when the container starts and are never
baked into the image.

The staging compose topology and Gitea Actions deployment are documented in
[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md). Pushes to `main` validate the
application, build the candidate image while staging remains online, stop the
application and scheduler briefly, back up the embedded database, migrate it,
and start the new release.

## 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

```sh
npm run check
npm run build
```

Everything you need to build a Svelte project, powered by [`sv`](https://github.com/sveltejs/cli).

## Creating a project

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

```sh
# create a new project
npx sv create my-app
```

To recreate this project with the same configuration:

```sh
# 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:

```sh
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:

```sh
npm run build
```

You can preview the production build with `npm run preview`.

> To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
The shared visual language and dashboard conventions are documented in
[docs/DESIGN_SYSTEM.md](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](docs/STAT_LEVEL_SCALING.md).