Canile Sanitario Bari — Adoption Platform

The system is a single Cloudflare Worker serving both a static React SPA (from R2-attached assets) and a dynamic Hono-based API. There is no separate frontend host, no separate API host, no separate database server. The deploy is one wrangler deploy.

Data lives in two stores: Cloudflare KV holds the structured dog profiles (name, breed, age in months and years, sex, size, status, health flags, personality tags, arrival date, ordered list of media keys) and the analytics counters (per-dog views, per-dog WhatsApp clicks, daily site-wide page views). Cloudflare R2 holds the photos and videos referenced by key from each dog profile. Media is served through a Worker route at /r2/:key that streams the object directly, so the public site never exposes raw R2 URLs.

This split exists because KV is optimised for tiny reads (great for a dog profile of a few hundred bytes) and R2 is optimised for blobs (great for photos averaging several hundred kilobytes). Mixing them would be wasteful — storing JPGs in KV would blow past the per-value size cap, and storing dog metadata in R2 would require an HTTP round-trip per attribute lookup.

Authentication is session-based. Admin credentials are hashed with PBKDF2 using a per-user 16-byte salt; on login the Worker mints a session token, stores it in KV with a 24-hour expiry, and returns it to the client. The token is sent in subsequent requests via a header and validated on every admin-route call. There is a single seed admin (admin/admin) that the shelter changes after first login.

The deployment topology means that every user request hits the edge, not an origin. There is no cold start, no region selection, no autoscaling concerns. Cloudflare runs the same Worker code in every PoP. The trade-off is that you give up the operational simplicity of a real relational database — every join, every secondary index, every aggregate has to be computed in JavaScript against KV. For a shelter with at most a few hundred dogs, that is massively the right trade; for a marketplace with millions of listings it would not be.

The public site has five route surfaces: the landing page, the dog listing, the dog detail page, the contact page, and the legal pages (privacy, cookie). Together they cover the full browse → discover → contact funnel.

Landing page

The landing page opens with an emotional hero ("trova il tuo nuovo migliore amico"), followed by a row of live stats (available dogs, adopted dogs, years of operation) computed on page load from KV counters. Below the stats is a featured-dogs carousel showing up to four randomly selected available dogs — randomising means visitors see different dogs on different sessions, surfacing the long tail rather than always the same four. A three-step "how to adopt" walkthrough sets expectations for the process, and a CTA banner invites other shelters to get in touch about adopting the platform itself.

Dog listing & discovery

The dog listing page at /cani is a responsive grid (2 columns on mobile, 3 on desktop) with advanced filters: size (piccolo / medio / grande), sex, and age category, plus a full-text search across the dog's name and breed. Each card shows a status badge (disponibile, riservato, adottato) and a subtle "someone is interested" heart icon when the dog has recently been contacted, which gives the page a signal of activity without ever revealing personal information. Empty states and skeleton loaders keep the page from feeling broken while data resolves.

Dog detail page

The dog detail page at /cani/:id is the conversion surface. It pairs a large photo gallery with thumbnails against a structured info column: breed, age in years/months, sex, size. Health badges show vaccinated, sterilized, microchipped status at a glance. Personality traits are rendered as chips drawn from a 14-tag predefined Italian vocabulary (affettuoso, giocoso, calmo, energetico, socievole…) — a controlled vocabulary keeps filtering useful and prevents the dataset from fragmenting into one-off adjectives. The primary action is a green WhatsApp CTA that, on mobile, is sticky to the bottom of the viewport so it never scrolls out of reach. Tapping it deep-links to WhatsApp with a pre-filled message referencing the dog by name.

Contact page

The contact page at /contatti is deliberately WhatsApp-first: the primary CTA is a big green button. Below it sit the shelter's name, address, and city, an accordion of four Italian adoption FAQs (the questions the staff get asked most), opening hours, and a Google Maps placeholder for the shelter location.

Cookie consent & legal

A cookie consent layer lives at the bottom of every page, backed by a React context that gates analytics until the user opts in. The privacy and cookie pages document the data the platform collects (which is minimal — page-view counts and WhatsApp-click counts, no personal identifiers).

The admin dashboard is a separate code-split bundle — loading the public site does not download Recharts, the admin form components, or the file upload tooling, because none of that is needed for a visitor browsing dogs.

Authentication

The login page at /admin/login takes a username and password, posts them to the Worker, and on success stores a session token in localStorage. The Worker validates credentials against a PBKDF2-hashed user record in KV, mints a token, stores it with a 24-hour expiry, and returns it. Every admin-route fetch sends the token in an X-Session-Token header; the Worker rejects expired or unknown tokens with a 401 and the React app routes back to the login page.

Add Dog flow

The Add Dog page at /admin/aggiungi is the most ergonomically dense screen in the app. It includes:

A drag-and-drop file area that also accepts click-to-upload, supporting up to 10 files per dog (photos or short videos). Each file uploads in real time with a status badge — uploading, uploaded, failed — and the order is reorderable so the first file becomes the primary photo used in the gallery and listing cards.

A structured form for the dog's profile: name, breed, age as separate years + months inputs (because shelter dogs are often "1 year 3 months" not just "1 year"), sex, size, and the health status flags. A multi-select for personality traits with the 14 predefined Italian chips plus an "add custom" affordance. A resizable description textarea. An arrival date picker.

On submit, the Worker writes the dog record to KV with the ordered list of R2 media keys, returns the new dog ID, and the UI shows a success toast with a direct shortcut to "Generate Instagram post for this dog".

Manage Dogs

The Manage Dogs page at /admin/gestisci adapts to viewport: a table on desktop (thumbnail, name, breed, age, size, status, actions) and a card list on mobile. A summary row at the top shows counters for disponibile / riservato / adottato; filter pills let staff narrow by status, and a name-search input handles ad-hoc lookup. Each row supports inline status change via a dropdown, delete (behind a confirmation dialog), edit (routes to /admin/modifica/:id), and a quick shortcut to the Instagram generator.

Analytics are first-party and fire-and-forget. The public site never loads a third-party tracker; instead, two custom hooks — usePageView on the page level and an inline contact handler on the WhatsApp button — issue async POST requests to the Worker that increment KV counters and return immediately. The user never waits on analytics.

The statistics dashboard at /admin/statistiche aggregates those counters into KPI cards (available, reserved, adopted, total WhatsApp contacts, total visits in last 30 days, most-viewed dog, most-contacted dog) and two Recharts visualisations: a horizontal bar chart of the top five most-contacted dogs, and a line chart of daily page views over the last 30 days. A CSV export built with xlsx bundles per-dog statistics (name, breed, status, arrival date, views, contacts) into a spreadsheet that staff can take into adoption meetings or share with municipal partners. The page also embeds a small "Cloudflare Analytics" card pointing to the dashboard for finer-grained edge metrics.

The shelter publishes regularly on Instagram, and writing a caption for every dog is repetitive work. The Instagram Post Generator automates it. Given a dog's profile, the generator composes a caption in the dog's voice ("Ciao, sono {nome}!"), narrates the personality traits in natural Italian, adds an age statement, describes the breed and size, appends health-status emojis, and closes with a gender-specific emotional appeal ("sto cercando una famiglia che mi sappia amare" for males, "…che mi sappia amare" with feminine agreement for females).

The shelter's name and city are tacked on, plus a curated hashtag block: size-specific hashtags (e.g. #canipiccoliadozione for small dogs), 14+ general adoption hashtags, and the shelter's own brand tag. The output is 30+ hashtags ready to copy with a single button — staff paste the caption into Instagram and post.

The frontend is React 19 with Vite 6 as the bundler and dev server, written in TypeScript 5.8 in strict mode. react-router-dom v7 handles client-side routing with the modern data-router API. State management is intentionally not Redux or Zustand — the data is almost entirely server-derived, so React Context (for auth and cookie consent) plus per-page useEffect fetches and a couple of custom hooks (usePageView, useConsentContext) covers everything without adding a state-management library.

The backend is Hono v4 running on the Cloudflare Workers runtime. Hono was chosen over alternatives like itty-router for its full middleware story (request validation, error boundaries, sub-routers) without the bundle cost of Express-style frameworks. All routes — dog CRUD, file upload, signed media serving, analytics counters, auth — live in a single worker entry file that Wrangler bundles into one Worker binary.

Code-splitting is deliberate: the admin bundle ships Recharts, xlsx, and all the admin form components, while the public bundle ships none of those. The result is a public site that loads fast on mobile — the audience for an adoption page is often someone on a phone, not a desktop user, and the shelter is in a region where bandwidth assumptions need to be conservative.

Responsive design uses JavaScript-based breakpoints rather than CSS media queries in components where the desktop and mobile layouts differ structurally (table vs. card list on Manage Dogs, side-by-side vs. stacked on the dog detail page). The break at 768px is read once from window.matchMedia and updated via a listener — this keeps the React tree consistent rather than relying on CSS to hide the wrong tree.

Every folder under src/ has a README.md with a purpose statement, a file list, and an Exports table. The exports table is generated by a custom script (scripts/generate-readme.ts) that uses ts-morph to walk every exported symbol in the folder, extract its name, kind (function / component / type / constant), and JSDoc summary, and rewrite the README's Exports section. Running npm run docs:generate keeps the docs in sync with the code.

Paired with the generator is a docstring checker (scripts/check-docstrings.ts): same ts-morph traversal, but it fails with a non-zero exit code if any exported symbol is missing a JSDoc comment. The npm run docs command runs generate then check, and the npm run check pre-deploy script runs tsc, vite build, and wrangler deploy --dry-run in sequence — so the project will not deploy if a new export is undocumented or if the production bundle fails to build.

This is the kind of guardrail that pays off specifically on solo projects: it stops past-me from handing future-me an undocumented function I no longer remember writing.

Setup is three Wrangler commands:

1. npx wrangler kv namespace create KV — provisions the KV namespace, returns an ID that goes into wrangler.json.

2. npx wrangler r2 bucket create shelter-media — provisions the R2 bucket already bound in wrangler.json under the MEDIA binding name.

3. Edit the vars block in wrangler.json: SHELTER_NAME, SHELTER_ADDRESS, SHELTER_CITY, WHATSAPP_NUMBER, WHATSAPP_DEFAULT_MESSAGE. These are the only variables that differ between shelters, which means the same codebase can be redeployed for a different shelter by editing five strings and running npm run deploy.

The project lives well inside the free-tier limits: Workers gives 100,000 requests/day, KV gives 100,000 reads + 1,000 writes/day, R2 gives 10GB of storage and a million Class A operations / month for free. A small-city shelter with a few hundred adoptable dogs and a few thousand visits per month fits comfortably. The economic model is "nothing per month, forever" until traffic grows, at which point the bill scales gradually — there is no abrupt step from free to a $100/month managed database.

The platform is actively deployed for Canile Sanitario Bari and serves as their primary digital presence. Before this, the shelter relied on Instagram for visibility and word-of-mouth and phone calls for inquiries — there was no searchable, filterable, always-up-to-date catalogue of adoptable dogs. The website now provides exactly that, and the WhatsApp-first contact flow meets people where they already are (WhatsApp is the dominant messaging channel in Italy) rather than forcing them through a contact form.

The analytics dashboard makes the shelter's engagement measurable for the first time: staff can see which dogs are getting attention, which dogs are getting no attention (and therefore need a fresh push on Instagram), and how many people are crossing the funnel from "view a profile" to "tap to message". That feedback loop is the actual product — the website is the surface, but the value is the visibility into what works.