45 KiB

Raw Blame History

MyKindlebox — Implementation Plan

Version: 1.1
Last Updated: 2026-06-20
Audience: AI developers
Scope: Base application only — core herd and litter management, no advanced features

Reference documents: app-design-document.md, tech-stack.md

Conventions

Each step has a single, concrete objective.
Each step ends with a Validation block — a specific check that confirms the step is complete and correct before moving on.
Do not proceed to the next step until the current step's validation passes.
No placeholders or stubs — every step should leave the codebase in a working, testable state.

Deferred: Authentication

The tech stack specifies single-user session token auth. Auth is intentionally out of scope for this base plan. All /api/* routes are unprotected in this phase. A future plan addendum will cover the login screen, token issuance, and route protection middleware. Do not add auth stubs or placeholders — implement it fully when that phase is added.

Phase 1 — Project Scaffolding

Step 1.1 — Initialize the monorepo structure

Create a root project folder named mykindlebox. Inside it, create two subdirectories: server for the backend and client for the frontend. Add a root-level README.md with the project name and one-line description.

Validation: The folder structure mykindlebox/server and mykindlebox/client exists. The README is present at the root.

Step 1.2 — Initialize the backend project

Inside server, initialize a Node.js project. Install Express as a dependency. Create a main entry file (index.js or index.ts) that starts an HTTP server on port 3001 and responds to GET /health with a JSON body of { "status": "ok" }.

Validation: Running the server and sending a request to http://localhost:3001/health returns HTTP 200 with { "status": "ok" }.

Step 1.3 — Initialize the frontend project

Inside client, scaffold a new React + Vite project. Install Tailwind CSS and configure it with a tailwind.config file. Install React Router v7. The default page should render the text "MyKindlebox" in the center of the screen.

Validation: Running the dev server and opening the browser shows a page with the text "MyKindlebox". No console errors.

Step 1.4 — Configure Tailwind design tokens

In the Tailwind config, extend the theme with the custom color tokens from the design document. Define all ten color values as named tokens matching the CSS variable names (e.g., surface, surface-raised, surface-sunken, border, text-primary, text-secondary, accent, accent-hover, accent-warm, danger).

Validation: Apply a background of bg-surface and text of text-text-primary to the root element. The page background should render as #F7F3EC and text as #1C1A16. Inspect in browser devtools to confirm the computed colors.

Step 1.5 — Load custom fonts

Add DM Sans and Inter via Google Fonts (or self-hosted). Configure Tailwind's font family extension so that font-display maps to DM Sans and font-body maps to Inter. Apply font-body to the root <body> element.

Validation: In the browser, inspect the computed font of any text element on the page. It should show Inter. Temporarily apply font-display to a heading and confirm it shows DM Sans.

Step 1.6 — Set up Docker Compose

Create a docker-compose.yml at the project root. Define two services: server (Node.js backend on port 3001) and client (Vite dev server or Nginx static on port 5173). Mount a named volume for the SQLite database file under server/data/.

Validation: Running docker compose up starts both services without errors. The health endpoint at http://localhost:3001/health and the frontend at http://localhost:5173 are both reachable from the host machine.

Phase 2 — Database

Step 2.1 — Install and configure Drizzle ORM

Inside server, install Drizzle ORM and the better-sqlite3 driver. Create a db directory inside server. Add a db/client.ts file that opens a SQLite connection to server/data/mykindlebox.db and exports the database instance.

Validation: Starting the server creates the file server/data/mykindlebox.db if it does not already exist. No errors on startup.

Step 2.2 — Define the Rabbit schema

In server/db/schema.ts, define the rabbits table with all fields from the data model in the design document: id, name, farm, sex, dob, weight_lbs, ear_number, location, status, color_name, photo_path, registration_number, gc_number, sire_id, dam_id, the seven locus fields (locus_a through locus_v), created_at, and updated_at.

sex must be constrained to the values: buck, doe, unknown.
status must be constrained to: active, for_sale, on_hold, sold, deceased, other.
sire_id and dam_id are self-referencing foreign keys to rabbits.id, nullable.
Add twelve freeform text columns for ancestors not in the database, covering all three ancestor generations:
- Generation 1 (parents): sire_name_text, dam_name_text
- Generation 2 (grandparents): paternal_grandsire_name_text, paternal_granddam_name_text, maternal_grandsire_name_text, maternal_granddam_name_text
- Generation 3 (great-grandparents): pp_grandsire_name_text, pp_granddam_name_text, pm_grandsire_name_text, pm_granddam_name_text, mp_grandsire_name_text, mp_granddam_name_text, mm_grandsire_name_text, mm_granddam_name_text All nullable text. The following rule governs when these columns are written and read:
Chain-authority rule: A _name_text column for a given ancestor slot is written only when the immediate parent node in that slot's chain has no FK (i.e., the chain is broken at the parent). Once a node resolves through a FK to a real DB record, all deeper generations in that branch come exclusively from that ancestor's own sire_id/dam_id/_name_text fields — the subject's own flat columns for those deeper slots are never written and never read. They are dead columns in an unbroken chain.

Concretely:
- sire_name_text is written only when sire_id is null.
- paternal_grandsire_name_text is written only when sire_id is null (chain broken at Sire). If sire_id is set, the Sire's Sire always comes from Sire.sire_id or Sire.sire_name_text — never from the subject's paternal_grandsire_name_text.
- The same rule applies recursively at every generation and every branch.
created_at and updated_at default to the current timestamp.

Validation: Running the Drizzle migration (or db.run equivalent) creates a rabbits table in the SQLite file with the correct columns. Open the database with a SQLite browser and confirm all columns and constraints are present, including all fourteen _name_text columns (two parents, four grandparents, eight great-grandparents).

Step 2.3 — Define the Litter schema

In the same schema.ts, define the litters table with fields: id, sire_id (FK → rabbits, nullable), dam_id (FK → rabbits, nullable), kindle_date, kit_count, notes, and created_at.

Validation: After migration, the litters table exists in the database with the correct columns. Confirm the foreign key references to the rabbits table are present.

Step 2.4 — Define the Settings schema

Define a settings table with fields: key (text, primary key) and value (text). This is a simple key-value store for app-wide configuration such as rabbitry name and weight display preference.

Seed it with two default rows on first run: rabbitry_name with a value of "My Rabbitry" and weight_unit with a value of "decimal_lbs".

Validation: After startup, the settings table exists and contains exactly two rows with the keys rabbitry_name and weight_unit.

Step 2.5 — Run and validate all migrations on startup

Configure the server so that on startup it runs all pending migrations automatically. Migrations should be idempotent — running them twice must not produce errors or duplicate data.

Validation: Stop the server, delete the database file, and restart. The database is recreated with all three tables and the two settings seed rows. Stop and restart again without deleting — no errors, no duplicate rows.

Phase 3 — Backend API

Step 3.1 — Add a global error handler and request logger

Add middleware to the Express app that logs every incoming request (method and path) to the console. Add a global error-handling middleware that catches unhandled errors and returns a JSON response with HTTP 500 and a body of { "error": "Internal server error" }.

Validation: Make a request to a non-existent route (e.g., GET /nonexistent). The server logs the request and returns HTTP 404. Trigger a deliberate error in a test route and confirm HTTP 500 is returned with the correct JSON body.

Step 3.2 — Rabbits API — GET all rabbits

Create a GET /api/rabbits endpoint. It must return an array of all rabbit records. Support the following optional query parameters:

sex — filter by buck, doe, unknown, or the special value kits (returns rabbits of any sex whose dob is within the last 56 days)
status — filter by any valid status value
search — case-insensitive partial match on the name field
sort — one of name, dob, weight_lbs, created_at (default: name)

Validation: With an empty database, the endpoint returns []. After inserting two test rabbits directly into the DB (one buck, one doe), confirm that GET /api/rabbits returns both, GET /api/rabbits?sex=buck returns only the buck, and GET /api/rabbits?search=<partial name> filters correctly.

Step 3.3 — Rabbits API — GET single rabbit

Create a GET /api/rabbits/:id endpoint. It must return the full rabbit record for the given ID. If no rabbit with that ID exists, return HTTP 404 with { "error": "Rabbit not found" }.

Validation: Requesting a valid ID returns the correct rabbit record with all fields. Requesting ID 99999 (nonexistent) returns HTTP 404 with the error message.

Step 3.4 — Rabbits API — POST create rabbit

Create a POST /api/rabbits endpoint. It must accept a JSON body, validate that name is present and non-empty, and insert the record. Return the newly created rabbit record with its assigned id and HTTP 201.

Reject requests missing name with HTTP 400 and { "error": "Name is required" }.

Validation: POST /api/rabbits with a valid body including at minimum { "name": "Test Rabbit", "sex": "buck" } returns HTTP 201 and the new record with an id. A subsequent GET /api/rabbits/:id with that ID returns the same record. Posting without a name returns HTTP 400.

Step 3.5 — Rabbits API — PATCH update rabbit

Create a PATCH /api/rabbits/:id endpoint. It must accept a partial JSON body and update only the provided fields. Return the full updated rabbit record. Return HTTP 404 if the rabbit does not exist.

Validation: Create a rabbit via POST. Send a PATCH with { "weight_lbs": 3.5 }. Confirm the returned record has weight_lbs: 3.5 and all other fields are unchanged. Send a PATCH to a nonexistent ID and confirm HTTP 404.

Step 3.6 — Rabbits API — DELETE rabbit

Create a DELETE /api/rabbits/:id endpoint. Return HTTP 204 on success. Return HTTP 404 if the rabbit does not exist. Before deleting, set sire_id and dam_id to null on any rabbit that references the deleted rabbit, to preserve referential integrity.

Validation: Create two rabbits where one is the sire of the other. Delete the sire. Confirm the child rabbit's sire_id is now null. Confirm the deleted rabbit returns 404 on a subsequent GET.

Step 3.7 — Rabbits API — GET ancestry

Create a GET /api/rabbits/:id/ancestors endpoint. It must return a nested object representing the rabbit's full 4-generation pedigree (root + 3 ancestor generations). Each node should include the rabbit's id, name, farm, sex, color_name, and their own sire_id / dam_id. Unknown ancestors (no FK and no freeform text) should be represented as null.

The endpoint must resolve each node using the chain-authority rule defined in Step 2.2:

If a node's parent resolved via FK, read the node's data from that parent DB record's own sire_id/dam_id/_name_text fields. Do not read from the subject's flat columns for that slot.
If a node's parent had no FK (chain broken), read the node's data from the subject's corresponding _name_text column.
Never mix sources within a branch: once the chain is broken, all remaining nodes in that branch come from the subject's flat columns; once the chain is intact, all nodes come from recursive ancestor records.

Validation: Create a set of 15 linked rabbit records (root → 2 parents → 4 grandparents → 8 great-grandparents). Call the ancestors endpoint on the root rabbit and confirm the returned tree has the correct nested structure with all 14 ancestors populated at the correct positions.

Then test the broken-chain case: create a root rabbit with sire_id null and sire_name_text = "Bob's Buck" and paternal_grandsire_name_text = "Old Bob". Call the endpoint and confirm the Sire node returns the freeform text "Bob's Buck" with no id, and the Sire's Sire node returns "Old Bob" from the subject's flat column.

Then test the unbroken-chain case: create a root rabbit with a real sire_id. Set a value in the subject's paternal_grandsire_name_text column directly in the DB (simulating stale or erroneous data). Call the endpoint and confirm the Sire's Sire node comes from Sire.sire_id or Sire.sire_name_text — not from the subject's flat column. The subject's flat column must be ignored.

Step 3.8 — Rabbits API — GET rabbit search (autocomplete)

Create a GET /api/rabbits/search?q=<query> endpoint specifically for the pedigree tree autocomplete. It must return only id, name, farm, and sex for up to 10 matching rabbits. Match on any portion of the name field, case-insensitive.

Also support an optional sex query parameter (buck, doe, or unknown) to restrict results to a single sex. This is required by the Add Litter form, which must restrict the Sire field to bucks and the Dam field to does.

Validation: With several rabbits in the database, querying ?q=jim returns only rabbits whose names contain "jim" (case-insensitive). Querying ?q=&sex=buck returns only bucks. Querying ?q=&sex=doe returns only does. The response contains no more than 10 results and only the four specified fields.

Step 3.9 — Litters API — CRUD endpoints

Create the following endpoints for litters:

GET /api/litters — return all litters, sorted by kindle_date descending. Include the sire and dam's name and id in each result (joined, not just IDs).
GET /api/litters/:id — return a single litter. Include sire and dam details. Include all Rabbit records whose sire_id and dam_id match the litter's parents and whose dob matches the kindle_date.
POST /api/litters — create a litter. Require kindle_date. Return HTTP 201 with the new record.
PATCH /api/litters/:id — update a litter's fields. Return the updated record.
DELETE /api/litters/:id — delete a litter. Return HTTP 204.

Validation: Create a litter via POST. Confirm it appears in GET all. Add a rabbit with matching sire_id, dam_id, and dob — confirm it appears in the GET single litter's kit list. Delete the litter and confirm it returns 404.

Step 3.10 — Settings API

Create two endpoints:

GET /api/settings — return all settings as a flat JSON object (e.g., { "rabbitry_name": "My Rabbitry", "weight_unit": "decimal_lbs" }).
PATCH /api/settings — accept a partial JSON object and update the provided keys. Only allow known keys (rabbitry_name, weight_unit). Reject unknown keys with HTTP 400.

Validation: GET /api/settings returns the two seeded defaults. PATCH /api/settings with { "rabbitry_name": "Belowland Rabbitry" } updates the value. A subsequent GET reflects the change. Sending an unknown key returns HTTP 400.

Step 3.11 — Dashboard stats endpoint

Create a GET /api/stats endpoint that returns a single JSON object with the following counts derived from the rabbits table:

herd — count of all rabbits with status active
bucks — count of active rabbits with sex buck
does — count of active rabbits with sex doe
kits — count of rabbits with status active whose dob is within the last 56 days (8 weeks). Use this age-window logic consistently; do not use the litter-join method.
for_sale — count with status for_sale
on_hold — count with status on_hold
sold — count with status sold
archived — count with status other or deceased. The dashboard stat card for this value must be labeled "Archived", not "Other", to distinguish it from the sex-based "Other" filter tab on the Herd page.

Validation: Insert rabbits with known statuses and DOBs. Call GET /api/stats and confirm each count matches the expected value. Insert a rabbit with a dob of today — confirm it appears in kits. Insert one with a dob of 57 days ago — confirm it does not. Confirm the archived key is present and correctly counts other + deceased status rabbits.

Step 3.12 — Photo upload endpoint

Create a POST /api/rabbits/:id/photo endpoint that accepts a multipart/form-data request containing a single image file in a field named photo. The endpoint must:

Validate that the uploaded file is an image (accept image/jpeg, image/png, image/webp only). Reject other types with HTTP 400.
Save the file to a designated uploads directory on disk (e.g., server/data/uploads/<rabbit-id>.<ext>).
Update the rabbit's photo_path field in the database to the saved file path.
Return the updated rabbit record with HTTP 200.

The POST /api/rabbits and PATCH /api/rabbits/:id endpoints remain JSON-only. Photo upload is always a separate step after the rabbit record exists.

Serve the uploads directory as static files at /uploads/* so the frontend can display photos via a standard <img src> URL.

Validation: Create a rabbit via POST /api/rabbits. Then send a POST /api/rabbits/:id/photo request with a valid JPEG file. Confirm the file is saved to disk and the rabbit's photo_path is updated in the database. Request the photo URL directly in the browser — it should display the image. Send a non-image file (e.g., a .txt file) and confirm HTTP 400 is returned.

Phase 4 — Frontend Foundation

Step 4.1 — Set up React Router with route definitions

Configure React Router v7 in the client app. Define routes for all paths in the IA:

/ → Dashboard page component
/herd → Herd page component
/herd/add → Add Rabbit page component
/herd/:id → Rabbit Detail page component
/herd/:id/edit → Edit Rabbit page component
/litters → Litters page component
/litters/add → Add Litter page component
/litters/:id → Litter Detail page component
/genetics → Genetics Calculator page component
/settings → Settings page component

Each route should render a placeholder component that shows the route name as a heading (e.g., "Dashboard", "Herd", etc.).

Validation: Navigating to each URL in the browser renders the corresponding placeholder heading with no errors. Navigating to /nonexistent should show a "Not Found" message (add a catch-all route).

Step 4.2 — Build the app shell layout

Create a persistent layout component that wraps all pages. It must include:

A left sidebar (240px wide) on screens wider than 768px containing: the app name "MyKindlebox" at the top, and navigation links for Dashboard, Herd, Litters, Genetics, and Settings.
A bottom navigation bar on screens 768px and below with five items: Dashboard, Herd, Litters, Add (links to /herd/add), and Settings.
A main content area to the right of the sidebar (or below the top on mobile) where the page component renders.

The active route should be visually highlighted in the navigation.

Validation: On a desktop-width browser, the sidebar is visible and the bottom nav is hidden. On a mobile-width browser (or using devtools), the sidebar is hidden and the bottom nav is visible. Clicking each nav item navigates to the correct route and highlights the active item.

Step 4.3 — Set up React Query

Install and configure React Query. Wrap the app in a QueryClientProvider. Create a shared api.ts utility file in the client that exports typed fetch functions for each API endpoint defined in Phase 3. All fetch functions should target http://localhost:3001/api.

Validation: In the Dashboard placeholder component, call GET /api/stats using a React Query useQuery hook. Confirm the raw response data is logged to the console without errors. The network tab in devtools should show a successful request to the backend.

Step 4.4 — Build shared UI components

Build the following small, reusable components. These will be used throughout the app. Each should accept the appropriate props and apply the correct design tokens from the Tailwind config.

Button — variants: primary (accent background), secondary (border only), danger (danger background). Sizes: sm, md.
Badge — displays a status label. Color-coded by status value: active (accent), for_sale (accent-warm), on_hold (text-secondary), sold (border), deceased (danger).
Card — a white (surface-raised) container with a border and subtle shadow.
PageHeader — a heading with an optional subtitle and optional right-side action slot.
EmptyState — a centered message with a title, description, and optional action button. Used when lists are empty.

Validation: Create a temporary /dev route that renders all five components with representative props. Visually confirm colors, sizes, and layout match the design tokens. Remove the dev route after validation.

Phase 5 — Dashboard Page

Step 5.1 — Build the stats bar

On the Dashboard page, fetch data from GET /api/stats. Render eight stat cards in a 4-column grid (2-column on mobile) using the Card component. Each card shows the label and count. Each card is a clickable link to the corresponding filtered herd view.

Show a loading skeleton (grey placeholder boxes) while the data is fetching. Show an error message if the request fails.

Validation: With rabbits of various statuses in the database, the dashboard stats cards display the correct counts. Clicking a stat card navigates to /herd (with the appropriate filter). The loading skeleton is visible briefly before data loads on a slow connection (simulate with devtools throttling).

Step 5.2 — Build the quick actions section

Below the stats bar, render three action buttons: "Add Rabbit" (links to /herd/add), "Record Litter" (links to /litters/add), and "View Herd" (links to /herd). Use the Button component with the primary variant for "Add Rabbit" and secondary for the others.

Validation: All three buttons are visible and navigate to the correct routes when clicked.

Below the quick actions, fetch the three most recent litters from GET /api/litters and display them as a small list. Each entry shows the sire × dam names, kindle date (formatted as "Month DD, YYYY"), and kit count. Each entry links to its litter detail page. Show the EmptyState component if no litters exist yet.

Validation: With litters in the database, the three most recent appear in the widget with correct names, dates, and kit counts. With no litters, the empty state renders. Each entry links to the correct /litters/:id route.

Phase 6 — Herd Page

Step 6.1 — Build the rabbit card component

Create a RabbitCard component. It accepts a rabbit record as a prop and renders: a placeholder breed silhouette image (SVG or static asset), the rabbit's name, color name and sex on the same line separated by a bullet, age (calculated from DOB as years/months) and weight on the same line, and litter/kit counts (these can be placeholder zeros until the API supports them). The entire card links to /herd/:id. Apply the Card component as the wrapper.

Validation: Render the card with a hardcoded rabbit prop. Confirm all fields display correctly. Confirm the card links to the correct route. A rabbit with no DOB should show "Age unknown" rather than crashing.

Step 6.2 — Build the herd filter bar

Above the rabbit grid on the Herd page, build a filter bar with:

A segmented tab control for sex: All / Bucks / Does / Kits / Other
A sort dropdown: Name / Age / Recent / Weight
A text search input with a small search icon
A view toggle: grid icon and list icon

Clarification on filter axes: "Kits" filters by dob within the last 56 days (age window, same as the dashboard stat). "Other" filters by sex = unknown — this is a sex-axis filter, not a status filter. This is intentionally different from the dashboard's "Archived" card, which filters by status. Do not conflate them.

Selecting any control should update the URL query parameters (e.g., ?sex=buck&sort=name&q=jim&view=list) and persist state on page reload.

Validation: Selecting "Bucks" updates the URL to include ?sex=buck. Typing in the search box updates ?q=<value> after a short debounce (no update on every keystroke). Toggling the view switch updates ?view=list or ?view=grid. Refreshing the page with those query params restores the filter state.

Step 6.3 — Build the herd grid view

Fetch rabbits from GET /api/rabbits using the active filter and sort state from the URL params. Render results as a responsive grid: 2 columns on mobile, 3 on tablet, 4 on desktop. Use the RabbitCard component for each rabbit. Show the EmptyState component when no results match the current filter. Show loading skeletons (matching the card size) while fetching.

Validation: With 10+ rabbits in the database, all appear in the grid. Applying the "Bucks" filter shows only bucks. Using the search input filters by name in real time. The grid is 2 columns on a 375px viewport and 4 columns on a 1280px viewport.

Step 6.4 — Build the herd list view

When ?view=list is active, render a compact table instead of the card grid. Columns: Name, Sex, Color, Age, Weight, Status. Each row links to the rabbit detail page. Zebra-stripe rows using the surface-sunken token for alternating rows.

Validation: Toggling to list view renders the table. All columns are populated correctly. Clicking a row navigates to /herd/:id. The same filters (sex, search, sort) applied in grid view also apply in list view.

Phase 7 — Add / Edit Rabbit Flow

Step 7.1 — Build the pedigree tree input component

Create a PedigreeTree component. It renders a 4-generation pedigree layout (root + 3 ancestor generations) with 15 nodes: the subject (new rabbit, non-editable label), 2 parents, 4 grandparents, and 8 great-grandparents. The layout follows standard ARBA pedigree orientation — root on the left, each generation branching right.

Each ancestor node is an interactive input. When focused, it shows a dropdown with a search box. Typing in the search box calls GET /api/rabbits/search?q=<query> and displays matching results. Selecting a result fills that node with the rabbit's name and stores the rabbit's ID. The node also shows two non-search options: "Enter manually" (accepts freeform text, saved to the subject's corresponding _name_text column with no FK) and "Unknown" (clears both the FK and the text field for that slot).

Chain-authority rule in the UI: This rule governs which nodes are editable and where their data is sourced.

When a node is resolved via FK (a real DB record is selected), all child nodes in that branch are automatically populated from that ancestor's own record and become read-only / locked. The user cannot enter freeform text into a child node whose parent resolved via FK. Locked nodes display the ancestor's data in a distinct locked style (e.g., greyed out with a lock icon) and are not interactive.
When a node has no FK (empty, freeform, or Unknown), its child nodes are editable. The user may search for a DB record, enter freeform text, or mark as Unknown. Values entered here are saved to the subject's flat _name_text columns.
This means "Enter manually" and "Unknown" options are only available on a node whose immediate parent has no FK. They must not appear on locked nodes.

When a DB-record ancestor is selected, cascade-populate its branch as deep as that ancestor's own records go. If a grandparent is a DB record but has no sire or dam recorded, the great-grandparent nodes in that branch remain editable (chain is broken at the grandparent level). If a grandparent has freeform text for its own parent, display that text in the locked node in muted style.

Validation: Render the component in isolation. Typing in the Sire node triggers a search request and shows results. Selecting a DB rabbit as Sire fills the node, auto-populates grandparent nodes from that rabbit's own record, and locks those grandparent nodes — they must not be interactive. Confirm the locked grandparent nodes do not show the search dropdown when clicked.

Clear the Sire node (set to Unknown). Confirm the grandparent nodes in the sire branch become editable again. Type a freeform name into the Sire's Sire node and confirm it saves to the subject's paternal_grandsire_name_text column with no FK.

Select "Unknown" on a parent node and confirm its child nodes are editable. Select "Enter manually" on a parent node and confirm its child nodes are also editable (chain is broken).

Step 7.2 — Build the rabbit details form

Create a RabbitDetailsForm component. It renders all fields from the design document's Step 2:

Name (text input, required, marked with an asterisk)
Farm / Prefix (text input, pre-filled from the rabbitry_name settings value)
Sex (three-button segmented control: Buck / Doe / Unknown)
Date of Birth (date input)
Weight (number input plus a unit toggle: "decimal lbs" or "lbs + oz", driven by the weight_unit setting)
Ear Number (text input)
Location (text input)
Status (select dropdown with all six valid values, defaulting to "active")
Color Name (text input)
Photo (file input, accepts image files only — image/jpeg, image/png, image/webp — shows a preview thumbnail after selection). Note: the photo is uploaded separately via POST /api/rabbits/:id/photo after the rabbit record is created. On the Add Rabbit page, the photo field is uploaded as a second request immediately after the initial POST /api/rabbits succeeds. On the Edit Rabbit page, a new photo selection replaces the existing one via the same endpoint.

Validation: Render the form in isolation with no initial values. The Farm field is pre-filled with the settings value. The weight unit toggle switches between a single decimal input and two inputs (lbs + oz). Submitting the form without a Name shows a validation error on the Name field without submitting. All other fields are optional.

Step 7.3 — Build the genetics section

Create a GeneticsForm component. It renders a collapsible section labeled "Genetics (optional)". When expanded, it shows pill-group toggles for each of the seven loci (A, B, C, D, E, En, V) with the correct allele options from the design document.

Below the loci selectors, render a read-only text field labeled "Generated color string" that displays a human-readable color description assembled from the selected loci (e.g., selecting aa, BB, CC, DD, ee produces "Self Black Non-Extension").

The section defaults to collapsed when adding a new rabbit. It defaults to expanded when editing a rabbit that already has any locus data set.

Validation: On the Add Rabbit page, the genetics section is collapsed by default and expands when clicked. Selecting loci updates the generated color string. On the Edit page for a rabbit with locus data, the section is expanded by default and shows the correct existing selections.

Step 7.4 — Build the review step

Create a ReviewStep component. It displays a read-only summary card of all entered data: the pedigree tree (ancestors listed by role), all detail fields with their values, and the selected genetics loci. Fields with no value should show a dash rather than being omitted.

At the bottom, render a "Save Rabbit" button (primary variant) and a "Back" button (secondary variant) that returns to the details step.

Validation: Populate all fields in the form steps and navigate to the review step. All entered values appear correctly. Empty optional fields show a dash. The "Back" button returns to the details form without losing any entered data.

Step 7.5 — Assemble the Add Rabbit multi-step flow

On the /herd/add page, compose the three steps (Pedigree Tree → Rabbit Details + Genetics → Review) into a linear wizard. Show a step indicator at the top (Step 1 of 3, Step 2 of 3, Step 3 of 3).

A "Next" button advances to the next step. The "Next" button on Step 1 is always enabled (pedigree is optional). The "Next" button on Step 2 is disabled until the Name field has a value. On Step 3, clicking "Save Rabbit" submits a POST /api/rabbits request with all collected data, then redirects to the new rabbit's detail page at /herd/:id.

Validation: Complete the full flow with valid data. Confirm the POST request is sent with all fields and the correct ancestor IDs. Confirm the redirect lands on the new rabbit's detail page. Attempt to advance past Step 2 without a Name — confirm the button is disabled and/or shows a validation error.

Step 7.6 — Build the Edit Rabbit page

On /herd/:id/edit, fetch the existing rabbit record and its ancestors. Pre-populate all form fields and the pedigree tree with the existing data. The flow is a single page (not a wizard) with all three sections visible: pedigree tree at the top, details form in the middle, genetics section (expanded) below.

Submitting sends a PATCH /api/rabbits/:id request with only the changed fields. On success, redirect to the rabbit's detail page.

Validation: Open the edit page for a rabbit with full data. All fields are pre-filled correctly. Change the weight and save. Confirm the detail page shows the updated weight and all other fields are unchanged. Confirm only the changed field appears in the PATCH request body (check network tab).

Phase 8 — Rabbit Detail Page

Step 8.1 — Build the rabbit detail left column

On /herd/:id, fetch the rabbit record. Render the left column with:

Photo (if photo_path is set, display the image; otherwise show the breed silhouette placeholder)
Name as a Display-size heading
Farm name as a secondary subheading (omit if null)
Status badge using the Badge component
A stats grid: Sex, DOB (formatted as "Month DD, YYYY"), Age (calculated), Weight, Ear Number, Location
Registration Number and GC Number (only rendered if non-null)
Color Name, followed by loci pills for any locus fields that are set

Validation: View the detail page for a rabbit with all fields populated. Confirm every field renders. View a rabbit with minimal data (name and sex only) — confirm no crashes and null fields are omitted gracefully. The status badge shows the correct color for each status value.

Step 8.2 — Build the read-only pedigree tree

In the right column of the rabbit detail page, fetch from GET /api/rabbits/:id/ancestors. Render the full 4-generation pedigree tree (root + 3 ancestor generations, 15 nodes) in the same visual layout as the entry tree, but read-only. Each ancestor node shows the rabbit's name and farm. Nodes with a database record are clickable links to that rabbit's detail page. Nodes with a freeform text value (stored in a _name_text column) display that text in a muted style with no link. Nodes where both the FK and text field are null display "Unknown" in a muted style.

Validation: On a rabbit with a full 4-generation tree in the database, all 14 ancestor nodes are populated and link to the correct detail pages. On a rabbit with unknown parents, those nodes display "Unknown" in muted text with no link. A node backed by freeform text displays the text in muted style with no link. Clicking a linked ancestor node navigates correctly.

Step 8.3 — Build the litter history section

Below the pedigree tree in the right column, query GET /api/litters filtered by the current rabbit appearing as sire or dam. Display matching litters in a compact table: partner name, kindle date, and kit count. Each row links to the litter detail page. Show nothing (no section heading) if the rabbit has no litter history.

Validation: For a doe with 3 recorded litters, the litter history table shows all 3 with correct dates and kit counts. For a rabbit with no litters, the section is absent.

Step 8.4 — Build the detail page action bar

At the top of the detail page, render an action bar with:

"Edit" button — links to /herd/:id/edit
"Add Litter" button — links to /litters/add with the rabbit's ID pre-filled as a query param (as sire or dam based on sex)
"Mark For Sale" button — sends PATCH /api/rabbits/:id with { "status": "for_sale" } and refreshes the page. If the rabbit's status is already for_sale, show "Mark Active" instead, which sets status back to active.
"Archive" button — shows a confirmation prompt before sending PATCH /api/rabbits/:id with { "status": "deceased" }. Uses the danger style.

Validation: Clicking "Edit" navigates correctly. Clicking "Mark For Sale" updates the status badge on the page without a full reload. Clicking "Archive" shows a confirmation prompt; cancelling does nothing; confirming updates the status.

Phase 9 — Litters

Step 9.1 — Build the litter card component

Create a LitterCard component. It renders: sire name × dam name (with "×" as a separator), kindle date formatted as "Month DD, YYYY", kit count (e.g., "3 kits"), and two buttons: "View Kits" linking to /litters/:id and "Edit" linking to the litter's edit state. Use the Card component as the wrapper.

Validation: Render the card with a hardcoded litter prop. Confirm all fields display correctly. A litter with no sire should show "Unknown × [dam name]". Both buttons link to the correct routes.

Step 9.2 — Build the Litters list page

On /litters, fetch all litters from GET /api/litters. Render them as a vertical list of LitterCard components, newest first. Add a "Record Litter" button in the page header action slot. Show the EmptyState component if no litters exist.

Validation: With litters in the database, they appear newest first. The "Record Litter" button links to /litters/add. With no litters, the empty state is shown.

Step 9.3 — Build the Add Litter form

On /litters/add, render a form with the following fields:

Sire (autocomplete search using GET /api/rabbits/search?q=&sex=buck, restricted to bucks only — or "Unknown")
Dam (autocomplete search using GET /api/rabbits/search?q=&sex=doe, restricted to does only — or "Unknown")
Kindle Date (date input, required)
Kit Count (number input, minimum 0)
Notes (textarea, optional)

If the page is loaded with a ?sire=<id> or ?dam=<id> query param (coming from a rabbit's detail page), pre-fill the corresponding field.

Submitting sends POST /api/litters. On success, redirect to the new litter's detail page.

Validation: Submit the form with a sire, dam, and kindle date. Confirm the POST is sent and the redirect lands on the new litter's detail page. Load the page with ?dam=<id> and confirm the dam field is pre-filled. Submit without a kindle date and confirm a validation error appears.

Step 9.4 — Build the Litter detail page

On /litters/:id, fetch the litter from GET /api/litters/:id. Render:

Page header: "Sire × Dam" as the title, kindle date as subtitle
Sire and Dam name links (to their respective rabbit detail pages)
Kindle date, and an expected wean date calculated as 8 weeks after kindle date, formatted as "Month DD, YYYY"
Kit table: Name, Sex, Color, Ear Number, Status badge, Weight. Each row's name links to the kit's rabbit detail page.
"Add Kit" button that links to /herd/add with ?sire=<id>&dam=<id>&dob=<kindle_date> pre-filled

Note (v1): The litter detail page derives its kit list by matching Rabbit records where sire_id and dam_id match the litter's parents and dob equals the litter's kindle_date exactly. This is intentional for v1. To prevent mismatches, the Add Rabbit form must default the DOB field to the litter's kindle date when launched from the "Add Kit" button — the user should not have to type it. A date-range tolerance is deferred to a future release.

Validation: View a litter with 3 kits. All kit rows appear with correct data and link to the correct rabbit detail pages. The expected wean date is exactly 56 days after the kindle date. The "Add Kit" button pre-fills the Add Rabbit form with the correct sire, dam, and DOB. Manually clear the DOB field on the Add Rabbit form before saving — confirm that kit does not appear in the litter's kit list (exact match enforcement).

Phase 10 — Settings Page

Step 10.1 — Build the Settings form

On /settings, fetch settings from GET /api/settings. Render a form with:

Rabbitry Name (text input, pre-filled from rabbitry_name)
Weight Display (segmented control: "Decimal lbs" / "lbs + oz", driven by weight_unit)

A "Save Settings" button sends PATCH /api/settings with the changed values and shows a success toast notification on completion.

Validation: Load the settings page and confirm the fields are pre-filled with the current values. Change the rabbitry name and save. Reload the page and confirm the new name persists. Switch the weight unit and confirm it persists across reload.

Step 10.2 — Build the database export

Add a "Export Database" button on the settings page. Clicking it sends a GET /api/export request. The backend should return the raw SQLite database file as a binary download with the filename mykindlebox-backup-<YYYY-MM-DD>.db and the content type application/octet-stream.

Validation: Clicking the export button triggers a file download in the browser. The downloaded file can be opened with a SQLite browser (e.g., DB Browser for SQLite) and contains the correct tables and data.

Phase 11 — Polish and PWA

Step 11.1 — Add a PWA manifest

Add a manifest.json to the client's public directory. Include: name ("MyKindlebox"), short_name ("Kindlebox"), start_url ("/"), display ("standalone"), background_color ("#F7F3EC"), theme_color ("#4A6741"), and at least one icon (192×192 PNG).

Validation: In Chrome devtools, open the Application tab → Manifest. All fields appear correctly with no warnings. On a mobile device (or devtools mobile emulation), the browser offers an "Add to Home Screen" prompt.

Step 11.2 — Add a service worker for offline shell caching

Register a service worker that caches the app shell (HTML, JS, CSS bundles, and the static silhouette image). When the device is offline, the app should load and display cached pages rather than a browser error. API requests that fail offline should show an inline "You're offline" notice rather than a crash.

Validation: Load the app in Chrome. Go to devtools → Application → Service Workers and confirm the service worker is registered. Enable "Offline" mode in devtools Network tab. Reload the page — the app shell loads. Navigate to /herd — the page renders (even if the rabbit list shows the offline notice).

Step 11.3 — Add reduced motion support

Wrap all CSS transitions and animations in a @media (prefers-reduced-motion: reduce) media query so they are disabled when the user has this OS-level preference enabled.

Validation: In devtools, enable "Emulate CSS prefers-reduced-motion: reduce" in the Rendering panel. Confirm that any hover transitions and loading skeleton animations are absent.

Verify that all interactive elements — buttons, links, form inputs, autocomplete dropdowns, segmented controls — are reachable and operable via keyboard alone (Tab to focus, Enter/Space to activate). All focused elements must have a visible focus ring using the accent color.

Validation: Starting from the top of any page, tab through all interactive elements. Every element receives a visible focus ring. No interactive element is skipped. The pedigree tree autocomplete dropdown can be opened, navigated with arrow keys, and confirmed with Enter, entirely without a mouse.

End of base implementation plan. Advanced features (genetics calculator, show tracking, health log, exports, public listing) are documented separately.

45 KiB Raw Blame History Unescape Escape