Running it

Rails runs on the host; Postgres, OpenSearch, MinIO and Mailpit run in Docker. The analyzers shell out to native binaries and inference runs on the GPU, so containerising the app would buy nothing and cost the debugger.

brew bundle          # native dependencies the analyzers need
bin/setup            # services, database, two tenants, generated API types
bin/dev              # web, worker, vite, and the codegen watchers

Tenants are subdomains

Add these to /etc/hosts:

127.0.0.1 things.test jons.things.test acme.things.test

Then jons.things.test:4242 and acme.things.test:4242.

Two tenants exist from the first seed on purpose. Single-tenant assumptions do not announce themselves — they leak through a scope someone forgot, months later — so every scenario in the suite should be exercised against both. See Tenancy.

What bin/dev runs

Process	Does
web	Rails, on PORT (4242 by default)
worker	Solid Queue, both pools — see Jobs
vite	the SPA, with HMR
codegen	dumps the GraphQL schema and regenerates the TypeScript from it

The Ruby schema is the source of truth and the TypeScript is generated from it, so the SPA cannot drift from the API without the types going red first. Both watchers have to be running for that to hold, which is why they are in bin/dev rather than a thing you remember to do.

The suite

bin/rails test

schema.graphql and the generated TypeScript are build products, not source. A clean checkout has neither, so anything that builds the frontend has to produce them first:

bin/rails graphql:dump_schema
npm run codegen

Before committing

bin/check-boundary

Nothing in this repository may name a host, a domain, or a secret — those are facts about a deployment, and they arrive through the environment. .env.example documents what. The check is wired into CI so the rule is greppable rather than remembered.