Three gaps in the Local Installation section of the README that a first-time reader hits when setting up locally.
Missing config.json5 step
After copying .env.example to .env, the reader also needs to create config.json5 from the template using the same pattern:
cp application/backend/config/config.json5.template application/backend/config/config.json5
The README does not mention this. Without the file, the backend crashes at boot with a schema validation error:
Error: Invalid config [{"instancePath":"","schemaPath":"#/required","keyword":"required","params":{"missingProperty":"smtp"},"message":"must have required property 'smtp'"}]
src/config.ts walks CONFIG_DIR (set in .env) for files matching .json / .json5, silently ignoring anything ending in .template. On a fresh clone the directory contains only config.json5.template, so the merged config is {} and AJV rejects it since the schema requires smtp.
The template's default empty-string SMTP fields pass validation, so no editing is needed for local dev — the file just needs to exist. Same pattern as .env.
Missing pre-commit install step
The project uses pre-commit hooks for formatting and linting checks on git commit (see .pre-commit-config.yaml and docs/CONTRIBUTING.md). The root README's Local Installation section doesn't mention this. New contributors following the README won't know to install pre-commit and will make commits without the hooks running locally, catching lint/format issues only in CI.
docs/CONTRIBUTING.md already has the install commands:
brew install pre-commit
pre-commit install
These should be surfaced in the Local Installation section of the README alongside the other one-time setup steps — the CONTRIBUTING doc is only linked from the very bottom of the README ("Want to contribute?" section), so a first-time reader won't find it until after they've already set up.
migrate / seed step ordering
Currently the README shows:
make db
yarn prisma:migrate
make seed
...with the "do not seed database in production" note added afterward.
Read top-to-bottom, this looks like three sequential steps. In practice these are two alternative paths:
- Local development:
make db && make seed — make seed runs migrations internally (see the seed target in Makefile).
- Production:
make db && yarn prisma:migrate — migrations only, no seed.
Suggested restructuring:
# For local development
make db
make seed # migrations + seed data
# For production (or any environment where seed data must not exist)
make db
yarn prisma:migrate # migrations only
Three gaps in the
Local Installationsection of the README that a first-time reader hits when setting up locally.Missing
config.json5stepAfter copying
.env.exampleto.env, the reader also needs to createconfig.json5from the template using the same pattern:The README does not mention this. Without the file, the backend crashes at boot with a schema validation error:
src/config.tswalksCONFIG_DIR(set in.env) for files matching.json/.json5, silently ignoring anything ending in.template. On a fresh clone the directory contains onlyconfig.json5.template, so the merged config is{}and AJV rejects it since the schema requiressmtp.The template's default empty-string SMTP fields pass validation, so no editing is needed for local dev — the file just needs to exist. Same pattern as
.env.Missing
pre-commitinstall stepThe project uses pre-commit hooks for formatting and linting checks on
git commit(see.pre-commit-config.yamlanddocs/CONTRIBUTING.md). The root README'sLocal Installationsection doesn't mention this. New contributors following the README won't know to install pre-commit and will make commits without the hooks running locally, catching lint/format issues only in CI.docs/CONTRIBUTING.mdalready has the install commands:These should be surfaced in the
Local Installationsection of the README alongside the other one-time setup steps — the CONTRIBUTING doc is only linked from the very bottom of the README ("Want to contribute?" section), so a first-time reader won't find it until after they've already set up.migrate/seedstep orderingCurrently the README shows:
...with the "do not seed database in production" note added afterward.
Read top-to-bottom, this looks like three sequential steps. In practice these are two alternative paths:
make db && make seed—make seedruns migrations internally (see theseedtarget inMakefile).make db && yarn prisma:migrate— migrations only, no seed.Suggested restructuring: