Repository navigation
Development
Laravel 13, Filament 5, PHP 8.5, PostgreSQL in production and development, in-memory SQLite in tests (CI also runs the tests against PostgreSQL). Frontend assets are built with Vite and Tailwind CSS 4.
The PHP version appears in exactly three places that change together: Dockerfile (ARG PHP_VERSION), composer.json and .devcontainer/devcontainer.json.
The devcontainer (GitHub Codespaces or VS Code) provides PHP, Composer, Node and Docker.
cp .env.example .env
docker compose up -d # app on http://localhost:8080 + PostgreSQL
docker compose exec app composer install
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate --seed
docker compose exec app php artisan db:seed --class=DemoSeeder
npm ci && npm run buildDemoSeeder creates a demo household with owner@example.com and member@example.com. With MAIL_MAILER=log, sign-in links appear in storage/logs/laravel.log.
vendor/bin/pint # format
php artisan test # feature tests, in-memory SQLiteCI runs Pint in test mode and the test suite on every push and pull request.
- Every input is validated on the server; use validated data only.
- Every route that calls an external API (e.g. Open Food Facts) or does expensive work has a rate limit.
- No API keys or secrets in the frontend;
VITE_*variables are public. - All UI text is translatable: English source strings with
__(), translations inlang/{de,es,pt,fr}.json. English is the main language and the fallback.tests/Feature/LocaleTest.phpfails when a string (or a category name) is missing in one of the languages. - Laravel's own texts (validation messages etc.) come from Laravel Lang (
laravel-lang/common, dev dependency) and are committed inlang/<locale>/. Update them withphp artisan lang:update; a new language withphp artisan lang:add <code>plus an entry inApp\Support\Locales. - No personal data of the maintainer in the repository (code, docs, commits, issues).
-
Modules and registries. Features are split into modules in
app/Modules/<Name>/, each with a service provider listed inbootstrap/providers.php. Modules register their parts in the registries inapp/Registries/:CategoryRegistry(supply categories),NavigationRegistry(Filament resources and pages, read by the panel provider)ProductLookupRegistry(product data sources by barcode, implementingProductLookupand returningProductInfo)StockRegistry(stock per category, implementingStockSourceand returningStockAmountwith usable and expired amounts)DashboardRegistry(Filament widgets on the dashboard; order from each widget's$sort; core registersSupplyStatusWidgetitself) andPrintoutRegistry(sections of the paper emergency copy, implementingPrintSection; core registersSupplySectionitself). Core code and other modules only read from the registries and never use a module directly;tests/Unit/ArchitectureTest.phpenforces this. A module keeps its models, policies, Filament resources and migrations in its own folder (migrations vialoadMigrationsFrom); factories stay indatabase/factories. Further registries are added with their first use. -
Modules so far.
Supply: food and water categories.Inventory: products, batches, locations, movements.OpenFoodFacts: barcode lookup with a local cache (off_cache), rate limit and offline fallback; tests fake the HTTP calls.Equipment: non-food checklists (areas from the BBK guidance, suggestions inSupport/Suggestions, status, check log), connected through theNavigationRegistryand thePrintoutRegistry. -
Scanner.
resources/js/scanner.js(zxing, loaded only on the Scan page via@vite) exposeswindow.holdoutScanner; the page waits for it, because the module may load after Alpine. Module views are loaded withloadViewsFrom(inventory::scan); the Filament theme also scansapp/Modules/**for Tailwind classes. -
Files. The
datadisk (storage/app/data, on theapp-storagevolume) is private and served only through signed temporary URLs at/files(Laravel'sserveoption). Product photos live inproduct-images/, Open Food Facts downloads inoff-images/. -
Barcodes are normalized to 13 digits by
App\Support\Barcode. -
Targets.
App\Support\SupplyTargetscalculates the target amount per category from the household size and target days, reading only theCategoryRegistry.App\Support\SupplyStatussets it against the stock from theStockRegistry(CategoryStatus: percent, days, missing,StockLevel) and gives the days of supply (the smallest category). -
Categories. The supply module registers the food and water categories with the BLE values.
CategorySeedersyncs them into thecategoriestable; the container runsmigrate --seedon every start, soDatabaseSeedermust stay idempotent and never create demo data (that isDemoSeeder). -
Sign-in. No passwords: passkeys (
laravel/passkeys,resources/js/passkeys.js), email links (LoginToken, 15 minutes, single use, hashed) and an authenticator app (App\Support\Totp, encrypted secret, recovery codes). Changing sign-in methods needs a recent sign-in (auth.password_confirmed_at), which all three methods set. Invitations (Invitation, 7 days) let the owner add people. -
Deployment follows the GitHub → GHCR → Coolify standard:
deploy/docker-compose.coolify.yml(app + queue worker), PostgreSQL as a separate Coolify resource on the externalcoolifynetwork, environment from Coolify. The container runs migrations andCategorySeederon every start (migrate --seed).
-
handbuch/<Page>.mdholds all details and is the source of the wiki. Always English. -
README.mdstays short: only updated for a new module or a changed quick start. - The wiki is generated, never edited by hand:
git clone "$(git remote get-url origin | sed 's/\.git$//').wiki.git" ../holdout.wiki
python3 scripts/build-wiki.py ../holdout.wiki
cd ../holdout.wiki && git add -A && git commit -m "Update wiki from handbuch" && git pushThe project page that introduces Holdout to new users lives in site/ and is published to GitHub Pages by .github/workflows/pages.yml on every push to main that touches site/. It is a single static page (index.html, style.css) without a build tool, external fonts or trackers. Always English.
-
Placeholders:
__SITE__(the URL fromsite/CNAME),__REPO__(owner/repository fromgithub.repository) and__DATE__(build date) are replaced at build time, so neither the domain nor the repository name is written into the pages twice. - Content: an overview of every feature with links into the wiki, the daily amounts per person, installation in three steps and an FAQ. When a feature, a module or the quick start changes, update the page together with the handbook.
-
SEO and GEO: title, description, canonical URL, Open Graph image (
og.png, the social preview), JSON-LD (SoftwareApplication,WebSite,FAQPage, whose questions must match the visible FAQ),robots.txt,sitemap.xmlandllms.txt, a plain-text summary for AI assistants. Keep concrete facts (numbers, sources, requirements) on the page: search engines and AI assistants quote them. -
IndexNow: after each deploy that changed
site/, the workflow reports the page to IndexNow (api.indexnow.org, shared by Bing, Yandex, Seznam, Naver and Yep; Bing also feeds the search of ChatGPT and Copilot). Google does not take part; there the sitemap in the Search Console does the job. The key is the 32-character hex name ofsite/<key>.txt, which contains exactly that key; it is public by design and proves that we own the domain. The reported URLs are every<loc>insitemap.xmlplusllms.txtandsitemap.xml, so a new page must be added tositemap.xml. A failed report never fails the deploy. Whether reports arrive is visible in the Bing Webmaster Tools under IndexNow; submit the sitemap there and in the Google Search Console once. -
Preview locally: copy
site/somewhere, replace the placeholders as the workflow does, and serve it withpython3 -m http.server. -
Setup (once): in the repository settings, Pages → Source: GitHub Actions and the custom domain from
site/CNAMEwith Enforce HTTPS; at the DNS provider aCNAMErecord from that domain to<github-owner>.github.io, not proxied.