Updates CLAUDE.md to reflect what the site actually is now (entity page +
invoicing, not just contact form):
- "What this is" expanded to two responsibilities.
- New "Storage stack dependency" section explaining the Postgres + MinIO
split, the storage repo, and the failure mode if storage is down.
- Stack list gains Sequel/pg, Prawn, aws-sdk-s3, AdminAuth, the two
external Docker networks, and postgres in the dev shell.
- New "Invoicing" section: routes (admin + public), storage model with
the uuid mass-assignment caveat, PDF rendering + Noto Georgian fallback,
frontend touch, and the open caveats (single-process number allocator,
UUID == access).
- Secrets table extended with ADMIN_*, ASXPIO_DB_PASSWORD,
ASXPIO_S3_ACCESS_KEY, ASXPIO_S3_SECRET_KEY and their rotation rules
(dual-repo update, push storage first).
- Records the URL-safe-password lesson from the deploy that broke prod
twice, with a generator one-liner.
- Recovery snippet uses a <prod-host> placeholder rather than the real
internal IP, since this file lives in a public repo.
Also drops the global-prefs lines from Hard Rules — those belong in the
user-level CLAUDE.md, not the project file.
Sequel guards primary keys against mass assignment, so passing uuid: to
Invoice.new raised MassAssignmentRestriction and turned every invoice
creation into a 500. Build the instance with the rest of the fields, then
set uuid as an attribute before returning.
start_with?('/admin') also matched /admin-invoice-form.js, returning 401
for the public JS asset that the New Invoice form depends on. Without it,
the "+ add line" button did nothing.
Require either the bare /admin path or a /admin/-prefixed one so sibling
assets in public/ that happen to share the prefix stay reachable.
Extends the .env heredoc the workflow drops on the prod host with:
- ADMIN_USER / ADMIN_PASSWORD — gate /admin/*
- DATABASE_URL — points at the storage stack's Postgres
- S3_* (endpoint, bucket, creds) — MinIO; S3_PUBLIC_ENDPOINT is the
s3.asxp.io hostname used only for
presigning so browser-facing URLs
resolve over Traefik+TLS.
Non-secret values stay hardcoded in the workflow; secrets come from
Forgejo. ASXPIO_DB_PASSWORD / S3 creds must match the corresponding
secrets on the storage repo or the app can't authenticate.
Extends the existing dark palette to cover the invoicing UI:
- .invoice-list: zebra-free table with right-aligned totals.
- .badge / .badge-pending / .badge-paid: small status chip.
- .items-table: per-row inputs for description/qty/unit price, .remove-row
button styling.
- .invoice-grid: two-column layout for the terms block (issued/due,
currency/GEL rate).
- .link-button: subdued "+ add line" affordance.
- .download-button: the prominent CTA on the public landing page.
- color-scheme: dark on date inputs so the native picker matches the
rest of the page.
No changes to existing rules.
Three admin templates:
- index: invoice list with status badge and link to detail.
- new: client + terms fields, dynamic line-item rows backed by
admin-invoice-form.js (add/remove + re-index of items[N][...] names).
- show: invoice detail, public URL to share, toggle-paid button.
One public template, invoice_public.erb, shown at /i/:uuid: client name,
number, total, status, and a single big download button to /i/:uuid/pdf.
All admin pages are noindex; same for the public landing (it's a
client-specific URL, not search-discoverable content).
Mounts AdminAuth (HTTP Basic on /admin/*) and adds two route groups:
- Admin (/admin/invoices): list, new form, create, show, toggle-paid.
POST /admin/invoices builds the Invoice, renders the PDF, uploads to
MinIO, then persists the row with the resulting pdf_key.
- Public (/i/:uuid): an HTML landing page showing client name, number,
total, and status badge, plus /i/:uuid/pdf which 302s to a short-lived
MinIO presigned URL. Anyone with the UUID can fetch the PDF — that's
the whole point of the link-based delivery.
The Invoice model is required only when DATABASE_URL is set, so the
contact-form site still boots in dev without Postgres. Invoicing routes
return 503 in that mode rather than crashing on first request.
S3 module wraps aws-sdk-s3 against MinIO. Two clients on purpose:
- The bytes-mover client points at S3_ENDPOINT (internal minio:9000 over
the storage Docker network).
- The presign-only client points at S3_PUBLIC_ENDPOINT (https://s3.asxp.io
via Traefik) so the URLs it mints resolve from a browser.
force_path_style on both because subdomain-style URLs would require wildcard
DNS under s3.asxp.io.
AdminAuth is a tiny Rack middleware that 401s any request under /admin
unless HTTP Basic credentials match ADMIN_USER / ADMIN_PASSWORD from env.
Fails closed if either env var is missing.
InvoicePdf.render(invoice) returns A4 PDF bytes. Layout: title + number,
horizontal rule, two-column FROM/BILL TO, meta strip (issued/due/currency/
status) bracketed by rules, line items table, right-aligned totals with
optional GEL equivalent, payment block (Bank of Georgia IBAN), optional
notes, repeating footer with issuer ID and page number.
Both party columns capture pdf.y after rendering and the global cursor jumps
to whichever ran longer — avoids the bbox cursor-restore footgun that was
collapsing the meta strip into the FROM column.
Noto Sans Georgian is registered as a fallback family so the Georgian legal
name renders without needing a separate text run.
Issuer details (legal name, tax ID, registration, address, bank) are
hardcoded as a constant — these are public on the rendered site already and
change rarely enough that a config file would be overkill.
Sequel::Model wrapper over the invoices table. Three responsibilities:
- Invoice.build takes form params (client, currency, GEL rate, items array)
and returns an unsaved Invoice with a freshly-allocated number, normalized
line items, and computed subtotal.
- Invoice.allocate_number scans for the highest INV-<year>-NNNN and
increments. Single-process deploy means no contention; if that changes
this needs a DB-side sequence per year.
- Instance methods: paid?, status, total, total_gel for the PDF renderer
and the public landing page.
Items are stored as JSONB; qty and unit_price are kept as strings on the
way in/out so BigDecimal arithmetic stays exact through the JSON round-trip.
DB.connect! opens a single Sequel connection from DATABASE_URL; DB.migrate!
runs Sequel migrations from db/migrations/.
The first migration creates the invoices table: uuid PK, unique invoice
number, client + currency fields, JSONB for line items, GEL conversion rate
captured at issue time, paid_at for the status toggle, pdf_key for the
MinIO object.
Prawn needs explicit TTFs to render anything beyond the built-in Latin
glyphs. Bundling Noto Sans (Latin/Cyrillic) and Noto Sans Georgian lets the
invoice PDF show both Latin and Georgian forms of the legal name.
OFL.txt is the upstream SIL Open Font License covering all five files.
- pg + sequel: connect to the storage stack's Postgres.
- prawn + prawn-table: render invoice PDFs.
- aws-sdk-s3: upload PDFs to MinIO and mint presigned download URLs.
Also pulls libpq-dev into the Docker build (for the pg gem) and the
postgresql client lib into the Nix dev shell.
The new asxpio/storage stack owns a Docker network named "storage" carrying
Postgres and MinIO. The app joins it (alongside traefik) so it can reach
postgres:5432 and minio:9000 by service name.
