App Template

Minimal fullstack template for typed feature development with coding agents.

Stack

• Rust + Actix Web (backend)
• Diesel 2.3 ORM (backend)
• Rust shared types with TypeScript generation (shared-types)
• TypeScript + SolidJS + Solid Router + Tailwind + DaisyUI (gui, admin-gui)
• Bash scripts for server setup and deploy (scripts)

Name Configuration

This template uses one config at project root:

• project.toml

Start by copying:

cp project.toml.template project.toml

Set at minimum:

[project]
name  = "myapp"
title = "My App"

[database]
url  = "sqlite:./app.db"

[server]
host = "127.0.0.1"
port = 8080

[gui]
port = 3030

[admin_gui]
port = 3031

[auth]
jwt_secret           = "change-me-in-production"
access_token_minutes = 15
refresh_token_days   = 30
otp_expiry_minutes   = 15

[email]
resend_api_key = "re_your_api_key_here"
from_address   = "noreply@example.com"

[deploy]
server_ip         = "203.0.113.10"
ssh_user          = "deploy"
domain_name       = "example.com"
letsencrypt_email = "admin@example.com"

Then apply naming across crate/package/docs:

scripts/init-project.sh

What This Template Includes

• GET /api/heartbeat in backend
• Embedded DB schema migrations via dedicated backend migrate binary
• Shared HeartbeatResponse type defined in Rust
• Generated TypeScript type consumed by GUI
• gui: Hello World + heartbeat status
• admin-gui: Hello World admin placeholder
• Email/password auth with OTP verification and JWT sessions (argon2 hashing, refresh tokens)
• systemd service template for backend
• nginx site template for GUI + /admin + /api reverse proxy with HTTPS
• certbot setup flow for TLS certificates
• pre-commit hook for Rust and frontend checks
• auth schema: users, identities, otps, refresh_tokens, contacts tables in backend/migrations/

Project Layout

• backend/: Actix API crate
  • src/auth/ — login, register, OTP, JWT, email, middleware
  • src/models/ — Diesel model structs with impl blocks
  • src/bin/migrate.rs — migration runner
• shared-types/: canonical API types + TS generator
• gui/: main SolidJS app
• admin-gui/: admin SolidJS app (served at /admin/)
• scripts/: setup, init, deploy, and server config templates
  • scripts/init-project.sh
  • scripts/setup-server.sh
  • scripts/deploy.sh
  • scripts/create-user.sh
  • scripts/install-git-hooks.sh
  • scripts/configs/backend.service.template
  • scripts/configs/nginx.conf.template
  • scripts/configs/nginx-temp-cert.conf.template
  • scripts/configs/server.toml

Local Run

0. Initialize the project (applies project naming across crate/package/docs):

cp project.toml.template project.toml   # edit as needed
scripts/init-project.sh

1. Generate TypeScript API types:

cargo run -p shared-types --bin generate_api_types

2. Run backend:

cargo run -p app-backend --bin migrate
cargo run -p app-backend

Config is loaded from project.toml; env vars override any TOML field. On the server, server.env (containing DATABASE_URL) is loaded by systemd as EnvironmentFile=.

3. Run main GUI:

cd gui
npm install
npm run dev

4. Run admin GUI:

cd admin-gui
npm install
npm run dev

Open:

• main GUI: http://127.0.0.1:3030
• admin GUI: http://127.0.0.1:3031

Git Hooks

Install repository-managed hooks:

scripts/install-git-hooks.sh

Pre-commit checks:

• cargo fmt --all --check
• cargo check --workspace
• cargo test --workspace
• gui: prettier --check . and npm run build
• admin-gui: prettier --check . and npm run build

Deploy Pattern

1. scripts/setup-server.sh
2. scripts/deploy.sh

Both scripts read project.toml by default. You can pass a custom config path if needed.

setup-server.sh provisions a Debian/Ubuntu VPS: base packages, firewall (ufw), fail2ban, hardened SSH, Rust toolchain, sccache, server.env with DATABASE_URL, and certbot TLS bootstrap.

deploy.sh syncs source via rsync, builds backend on server with sccache caching, runs migrations, installs systemd and nginx config (HTTPS with LetsEncrypt), and uploads built GUI dists.

Development Model

Read DEVELOP.md for the type-driven feature workflow.