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

```sh
npm run db:migrate
```

The default file is `data/shd-build.db`. Copy `.env.example` to `.env` and set a
different location if needed.

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:

```sh
npm run db:seed-users
```

The seed creates administrator `Aewyn` and standard user `Quartermaster`. It
generates and displays strong temporary passwords once, then stores only salted
Argon2id hashes.

## Develop

```sh
npm run dev
```

## Encrypted environment files

Keep development, staging, and production settings in the committed, encrypted
`.env.development`, `.env.staging`, and `.env.production` files. Keep private
decryption keys only in the ignored `.env.keys` file and 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` and replaces staged plaintext
environment files with encrypted versions. Git has no pre-add hook. Use
`npm run env:stage` instead of directly adding these two files.

Keep `.env.keys` out of Git and retain a backup. Production deployments receive
`DOTENV_PRIVATE_KEY_PRODUCTION` through their secret manager; do not copy the
keys file to the server.

## 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](docs/DEPLOYMENT.md) documents the staging Compose topology
and Gitea Actions deployment. A push to `main` validates the application, builds
the candidate image while staging stays online, stops the application and
scheduler for the database backup and migration, then starts the release.

## 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` and `dev.shd.build`. Use `localhost`
for direct local development.

Magic links require `SMTP_HOST`, `SMTP_PORT`, `SMTP_SECURE`, `SMTP_USER`,
`SMTP_PASSWORD`, and `SMTP_FROM`. Use `SMTP_SECURE=true` on port 465. Use
`false` on port 587 and upgrade with STARTTLS. An account owner activates an
email identity by following a 15-minute, single-use verification link.

## Validate

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

[`sv`](https://github.com/sveltejs/cli) creates and configures Svelte projects.

## Creating a project

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

Install dependencies with `npm install` (or `pnpm install` or `yarn`), then
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

Build a production version:

```sh
npm run build
```

Preview the production build with `npm run preview`.

> Deployments may require an [adapter](https://svelte.dev/docs/kit/adapters) for
> the 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).