MK Framework sample applications

Thirty-three runnable applications show how a small Ruby JSON API and a JavaScript UI can grow from a todo list into products with real workflows. Each pair lives in sample_appNN/api and sample_appNN/ui, with its own short guide. The API uses the published mk_framework Ruby gem; the UI uses the published mkframe npm package. Neither runtime resolves from the reference checkouts in tmp/.

Browse the API framework source and UI framework source. The latter documents components, Pug templates, DOM updates and its resource API. This repository is the runnable showcase: application code, fixtures, local artwork, request specs and a gallery that links every UI.

You need Ruby 3.3+, Bundler, Node 20.19+ or 22.12+, and npm. From a fresh checkout:

bundle install
cd sample_app01
bundle exec rake setup
bundle exec rake dev

Open Daybook at http://127.0.0.1:5181/. Its JSON API listens on http://127.0.0.1:9401. setup installs the selected API's gems and the shared npm lockfile, applies migrations and adds guarded demo data. On later runs, start it with cd sample_app01 && bundle exec rake dev; starting never migrates or seeds. Press Ctrl-C to stop both owned processes.

To try another app, replace sample_app01 with any directory in the catalog below. Each app has the same setup, dev and spec tasks. For example:

cd sample_app24
bundle exec rake setup
bundle exec rake dev
# UI:  http://127.0.0.1:5204/
# API: http://127.0.0.1:9424/

The default ports follow UI = 5180 + app number and API = 9400 + app number. Set UI_PORT and API_PORT when starting one pair if those ports are occupied. Logs go to artifacts/development/ at the repository root. If you want only an API, go to sample_appNN/api, run bundle install, bundle exec rake db:seed, then bundle exec rake dev (Puma defaults to port 3000). The API README documents its endpoints and data rules.

The fastest tour is to seed and launch all apps, then open the gallery:

bundle install
bundle exec rake setup
bundle exec rake dev
# http://127.0.0.1:5180/samples.html

rake setup installs every API bundle, installs npm dependencies from package-lock.json, migrates and explicitly seeds each app. rake dev launches 33 Puma APIs and one Vite server. It checks the needed ports before launching and stops its children on Ctrl-C. This uses more memory than one pair; start an individual app while developing. The collection UI runs on port 5180, and its links use /sample_appNN/ui/. APIs run on ports 9401–9433. Setup can be repeated: seed tasks guard existing demo collections, while each API remains responsible for its own data.

If another service already owns a collection port, select a different range: UI_PORT=15180 API_BASE_PORT=19400 bundle exec rake dev serves the gallery on 15180 and the APIs on 19401–19433. The Vite proxy follows those API ports automatically.

You can also start one pair from the repository root with bundle exec rake 'start_app[24]'. The quotes matter in shells such as zsh. bundle exec rake seed refreshes explicit demo fixtures for all pairs, while bundle exec rake ui:build builds the whole frontend collection.

The first six apps are compact enough to trace from an HTTP request through a controller, model and response handler. Later apps combine validation, transactions and retained history. Every row links to an app guide with exact start commands; its api/README.md is the detailed contract.

• Start with the request flow: Daybook is direct CRUD; Tend adds validation and check-ins; Forma changes response envelopes. Fieldnotes introduces nested resources and parent scoping.
• See operational rules: Studio Hours rejects overlapping bookings; Assembly handles capacity and waitlists; Batchline allocates material and protects quality-gated dispatch.
• Study durable decisions: Edition freezes published issues; Common Ground preserves ballots and recounts; Biome, Hexworld, and Gridlight compare preserved simulation branches.
• Explore distinctive interfaces: Pinpoint is a map directory; Digsite draws trenches and stratigraphy; Kinship maps uncertain evidence; Nightjar connects sightings to survey effort.

sample_appNN/
  Readme.md       short description and commands for the pair
  Rakefile        setup, dev and spec from this directory
  api/            Rack app, Sequel models, migrations, seed, request specs
  ui/             Vite entry, MkFrame components, Pug, styles and artwork
frontend/         shared UI behavior for a few related workspaces
Rakefile          collection setup, tests and process supervision
samples.html      gallery for the all-app Vite server
tmp/              ignored reference checkouts; never a runtime dependency

Each API keeps its own Gemfile and Gemfile.lock. The root Gemfile supplies Rake for collection commands. The root package.json and lockfile install the UI tooling and mkframe@0.1.0 from npm; there is no per-app npm install. Vite serves the selected UI at / when you run an app pair, or all UIs under their named paths in collection mode. It proxies /api/backendN to the matching Puma process, so the browser talks to its app through the same local origin.

The framework's route and response conventions are visible in the API source. Controllers accept and scope input, Sequel models enforce persistence rules, and response handlers format JSON. The UI source demonstrates MkFrame components and Pug templates around those APIs. The source is intentionally readable: each app retains domain code alongside its tests, instead of hiding behavior behind a shared showcase backend.

Databases are local SQLite files under each API directory and are ignored by Git. db:migrate changes schema; db:seed adds illustrative fixtures. Tests use isolated databases, so running specs does not require deleting local demo data. Backends do not migrate or seed during boot. Some later apps contain demo accounts and protected workspaces; find their local credentials and boundaries in the relevant API README. The shop is a single-user demonstration with no checkout or payments, and car reservations send no outbound messages.

Most samples work entirely from seeded local data. The weather app can fetch live forecasts with OPENWEATHERMAP_API_KEY; Night Archive can fetch NASA data with NASA_API_KEY. Their seeded experiences and request specs do not require those keys. Pinpoint's map can load third-party map tiles in a browser. Generated decorative art is stored locally in each UI's assets/ folder; its metadata sits next to the image.

bundle exec rake          # every API's request suite
bundle exec rake ui:build # all 33 UIs through Vite
cd sample_app14 && bundle exec rake spec # one API suite

Each API keeps its request and domain tests in api/spec/; several suites also check migrations and production boot. Run bundle exec rake routes inside an api/ directory to inspect its compiled routes. If an API fails to start, inspect artifacts/development/sampleN.log; the paired UI log is sampleN-ui.log. An occupied port stops startup before this run launches anything.

Each app's Readme.md gives the shortest route to a running pair; its api/README.md describes the data and HTTP contract. The code and art are MIT licensed; see LICENSE.