Kalmiya

Authentication starter for a Rails + React (Superglue) application.

What this repo is: a Rails 8 edge app wired to a Superglue 2 (React 19 + Mantine 9) front-end, with signup / sign-in / password reset wired end-to-end. No business models yet — the goal is to land on a clean substrate for building the rest of the Kalmiya-archetype platform without retro-fitting auth later.

This is a personal/solo project (forked and developed in the open), not a gem. Treat the codebase as a starting point, not a finished product.

---

Stack

Layer	Choice
Backend	Ruby 4.0.6 + Rails edge (8.2.0.alpha, load_defaults 8.1)
Database	PostgreSQL 18
Cache / Queue / Cable	Solid Cache, Solid Queue, Solid Cable
Frontend	React 19 + Superglue 2.0-beta + Mantine 9
Assets	Propshaft (Rails) + esbuild (JS) + PostCSS (CSS, Mantine preset)
Lint/format	Biome 2.5 (JS/TS/CSS) · Rubocop Rails Omakase (Ruby)
Deploy	Kamal + Thruster
IDs	UUID primary keys via custom gem ueid
Passwords	argon2 (has_secure_password algorithm: :argon2)

Everything is pinned via .ruby-version, .node-version, packageManager in package.json, and the Gemfile.lock.

---

Quickstart (dev)

Two supported workflows. Devenv is the recommended one for this project — it brings up Postgres 18 + Redis + all four dev processes (web, JS watch, CSS watch, Storybook) in one tree.

Option A: devenv (recommended)

Prerequisites: Lix or Nix with flakes, plus devenv.

devenv up            # starts postgres, redis, web (:3000), js, css, storybook (:6006)

Then open http://localhost:3000 (Rails) and http://localhost:6006 (Storybook).

devenv up is a process-compose tree — Ctrl+C in the TTY stops everything. Use devenv up --detach for headless operation; logs land under .devenv/state/process-compose/.

Option B: plain (no devenv)

Prerequisites: Ruby 4.0.6, Node 26.4.0, Yarn 4.17.1, a local Postgres + Redis reachable on default sockets.

bin/setup --skip-server   # bundle install, db:prepare, log:clear, tmp:clear
yarn install              # not part of bin/setup — runs separately
bin/dev                   # Rails server on :3000

You'll also want yarn build --watch and yarn build:css --watch in separate terminals. Procfile.dev exists but bin/dev does not read it; use devenv if you want one-command orchestration.

---

Project layout

app/
  controllers/        session, password, user, root controllers
  models/             User (argon2), Session, Current
  views/              ERB templates (server-rendered)
  javascript/         Superglue pages + components (React, Mantine)
  assets/             stylesheets (PostCSS), builds/ (gitignored output)
config/
  application.rb      load_defaults 8.1
  database.yml        Postgres defaults; kalmiya_development + kalmiya_test
  deploy.yml          Kamal config
db/
  migrate/            migrations (users, sessions)
  schema.rb           checked in (43f2ab6 refresh for Rails 8.2)
.github/workflows/    CI
.kamal/               Kamal secrets + hooks

Routes (config/routes.rb):

Path	Controller#action
/	root#index
/session	SessionsController (new/create/destroy)
/user	UsersController (new/create)
/passwords/:token	PasswordsController
/up	health check
/letter_opener	dev-only mail preview

---

Superglue architecture (important)

This is not a standard ERB app. Every page has two files under app/views/<resource>/:

1. ERB layout shell — sets up props, renders the page metadata, then mounts the React tree. The ERB file is what Rails serves.
2. .jsx Superglue page — the React component that renders the actual UI.

State, navigation, and forms are handled by Superglue's data-sg-visit, usePage, and useDispatch primitives, not by Rails UJS. The user-facing flow is a JSON-over-HTML hybrid: the ERB layer hands the React tree a serialized props object (the page slice + CSRF + URL); Superglue owns client-side state and dispatches.

If you're new to Superglue, read @thoughtbot/superglue docs before touching views — the patterns are specific.

---

Development commands

Command	What it does
bin/dev	Rails server on :3000 (no Foreman)
bin/setup	bundle install + db:prepare + clean (idempotent)
bin/setup --reset	db:reset instead of db:prepare
bin/setup --skip-server	setup without exec'ing bin/dev
bin/rubocop	Ruby lint (Omakase)
bin/brakeman / bin/bundler-audit	security scanners
bin/ci	config/ci.rb aggregate CI script
yarn build	one-shot JS build via build.mjs
yarn build:css	one-shot CSS build via PostCSS
yarn storybook	Storybook dev on :6006
yarn build-storybook	Storybook static build
yarn lint / yarn format	Biome lint / format
yarn check / yarn check:fix	Biome check (lint + format) / with --write

---

Testing

Default Rails test suite lives under test/ (not yet populated beyond the Rails generator output). bin/rails test and bin/ci are wired up. System tests are commented out in config/ci.rb — Storybook is the primary component-level test surface for the React side.

---

CI

.github/workflows/ runs bin/ci on push. The script chains bin/setup --skip-server then fans out Rubocop, bundler-audit, brakeman, Rails tests, and the test database seed-replant in parallel.

Known issue (2026-07-17): the bin/importmap audit step in config/ci.rb is a no-op — bin/importmap isn't stubbed in this repo. That line fails until it's removed or the binary is added.

---

Deployment

.kamal/ and config/deploy.yml are pre-wired for Kamal + Thruster. The repo is a single-process Rails app; Thruster fronts Puma for HTTP asset caching and X-Sendfile acceleration.

This repo is not deployed yet — Kamal config is staged but no target host is defined.

---

Working agreement

This is a solo-founder repo. Commits are one logical unit each, no batching. Branch strategy: trunk mainline, no PRs required in general — but this README rewrite was done on a branch because you asked for a PR. Review flow lives on the Git host (Gitea at git.anteater-wall.ts.net/brooklyn/kalmiya.git).

For contributor / architecture context, read AGENTS.md in this repo. It is the canonical project narrative — this README is the on-ramp, AGENTS.md is the deep dive.

---

License

TBD. Treat as "all rights reserved" until a LICENSE file is added.