shd.build/docs/architecture.md

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.