86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# SHD.build architecture
|
|
|
|
This project is intentionally being built in vertical slices.
|
|
|
|
## Planned stack
|
|
|
|
- SvelteKit 2 / Svelte 5 with TypeScript
|
|
- Embedded Turso Database via `@tursodatabase/database` for durable application data
|
|
- Auth.js-compatible server authentication with Discord OAuth and credentials providers
|
|
- Argon2id password hashing, server-side sessions, CSRF protection, and role checks
|
|
- Browser `localStorage` only for anonymous build drafts
|
|
|
|
## Product boundaries
|
|
|
|
- Public: browse, sort, and view published builds and guides.
|
|
- Anonymous: create and edit local drafts.
|
|
- Authenticated: publish, rate, comment, favorite, copy, and manage owned builds.
|
|
- Editor: manage builder source data.
|
|
- Admin: manage users, roles, source data, and audit history.
|
|
|
|
Authorization must be checked on the server for every mutation. Hiding an admin link is not authorization.
|
|
|
|
Local credentials are stored as Argon2id PHC strings with a unique random salt
|
|
per password. Current work factors follow OWASP's 19 MiB / 2 iteration /
|
|
single-lane minimum profile and can be increased over time; successful login
|
|
will eventually rehash credentials whose parameters are outdated.
|
|
|
|
## Database runtime
|
|
|
|
The application uses Turso Database in-process through its native Node package.
|
|
It opens a local SQLite-compatible database file and does not use Turso Cloud,
|
|
libSQL HTTP, remote replicas, auth tokens, or synchronization.
|
|
|
|
The database defaults to `./data/shd-build.db`. Production deployments must
|
|
provide a persistent writable filesystem and can override the location with
|
|
`TDR_DATABASE_PATH`. This rules out ephemeral serverless filesystems unless a
|
|
persistent volume is attached.
|
|
|
|
## Increment plan
|
|
|
|
1. Product shell and anonymous local-draft builder.
|
|
2. Embedded Turso migrations, repositories, and seed data.
|
|
3. Credentials and Discord authentication.
|
|
4. Full equipment/stat builder driven by database definitions.
|
|
5. Publishing, discovery, ratings, comments, favorites, and copy flow.
|
|
6. Rich build guides and moderation.
|
|
7. Admin editors, validation, audit log, and data import/export.
|
|
# Administrator bootstrap
|
|
|
|
The first successfully authenticated user is promoted to `admin` if the
|
|
database does not contain an administrator. Promotion uses one conditional
|
|
database update so concurrent first sign-ins cannot both become administrators.
|
|
Once an administrator exists, later sign-ins never alter roles.
|
|
|
|
# Database backup and restore
|
|
|
|
Embedded Turso databases contain contributor-entered source data and must be
|
|
preserved across development changes.
|
|
|
|
Create a timestamped development backup:
|
|
|
|
```sh
|
|
npm run db:backup
|
|
```
|
|
|
|
Create a production backup:
|
|
|
|
```sh
|
|
npm run db:backup:production
|
|
```
|
|
|
|
The scripts write versioned JSON documents beneath `data/backups/` by default.
|
|
That directory is ignored by Git because backups contain private user data,
|
|
including password hashes.
|
|
|
|
To restore, first create an empty database and apply the schema. Then run:
|
|
|
|
```sh
|
|
npm run db:restore -- data/backups/<backup-file>.json
|
|
```
|
|
|
|
The restore operation refuses to import into any database containing records.
|
|
This guard prevents accidental merging or overwriting of contributor data.
|
|
Stop the application before backup or restore so the embedded database file is
|
|
not locked by another process.
|