133 lines
5.7 KiB
Markdown
133 lines
5.7 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.
|
|
|
|
# ISAC audit and compensating reversals
|
|
|
|
Every successful ISAC mutation appends an event to `audit_log` through the
|
|
shared server audit utility. Events identify the operator, operational category,
|
|
specific action, target entity, timestamp, and useful before/after evidence.
|
|
The audit registry is read-only and requires `audit.view`; the seeded Auditor
|
|
role grants that permission without granting mutation capabilities.
|
|
|
|
Audit history is immutable. “Revert” is implemented as a new compensating
|
|
mutation rather than deletion or modification of the original event:
|
|
|
|
1. The operator must independently hold `audit.revert`.
|
|
2. The original action must be explicitly supported and contain a usable
|
|
before-snapshot.
|
|
3. The UI requires a second, explicit confirmation.
|
|
4. The server reloads the target and compares it with the original
|
|
after-snapshot, ignoring bookkeeping timestamps. A mismatch means newer work
|
|
exists and blocks automatic compensation.
|
|
5. Referenced roles, permissions, and relationships are revalidated before
|
|
restoration. Restoring administrator authority additionally requires full
|
|
administrative access.
|
|
6. The server restores the previous state and appends an `audit.reverted` event
|
|
whose target is the original audit-event ID.
|
|
7. A successfully reverted event cannot be reverted again.
|
|
|
|
Unsupported destructive identity operations, account deletion, incomplete
|
|
snapshots, stale targets, and events whose dependencies no longer exist are
|
|
marked non-reversible or rejected. Recovery for those cases requires a
|
|
specialized workflow rather than inferred database writes.
|
|
|
|
# System metrics
|
|
|
|
The read-only `/admin/metrics` route requires `metrics.view` and collects a
|
|
point-in-time process-local health snapshot. Node and operating-system APIs
|
|
provide process CPU and memory, event-loop utilization and delay, host memory,
|
|
load average, core count, platform, and uptime. Embedded Turso pragmas provide
|
|
page allocation, page size, and free-page information; aggregate SQL queries
|
|
provide application record volumes.
|
|
|
|
The interface refreshes on demand and may poll every ten seconds while the
|
|
operator keeps auto-refresh enabled. CPU and event-loop values are deltas from
|
|
the previous server-side sample, so the first or infrequently requested sample
|
|
is directional rather than a monitoring-grade time series. Production alerting
|
|
and historical analysis should eventually use a dedicated external telemetry
|
|
system. This surface deliberately omits secrets, environment-variable values,
|
|
and full database paths.
|