Flesh out project README
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
parent
c961e48953
commit
77cb71b7aa
|
|
@ -1,3 +1,107 @@
|
||||||
# MyKindlebox
|
# MyKindlebox
|
||||||
|
|
||||||
A self-hosted rabbitry (rabbit breeding herd) management web app.
|
A self-hosted rabbitry (rabbit breeding herd) management web app — track your
|
||||||
|
rabbits, their pedigrees, litters, and genetics. Single-user, self-hosted, and
|
||||||
|
designed to replace a legacy PHP herd-management site.
|
||||||
|
|
||||||
|
The core differentiator: **adding a rabbit starts from a pedigree tree, not a
|
||||||
|
blank form.** The 3-generation ancestor tree (sire/dam and their sires/dams) is
|
||||||
|
the primary data-entry surface, with inline autocomplete against your existing
|
||||||
|
herd and graceful fallback to freeform text for bought-in or unknown ancestors.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Pedigree-first rabbit entry** — build the ancestor tree first, then fill in
|
||||||
|
details; unknown ancestors can be stored as plain text so entry is never
|
||||||
|
blocked by missing records.
|
||||||
|
- **Herd management** — name, sex, DOB, weight, and status
|
||||||
|
(`active` / `for_sale` / `on_hold` / `sold` / `deceased` / `other`).
|
||||||
|
- **Litters** — record kindle dates and kit counts; the kit list is derived
|
||||||
|
live from Rabbit records (no separate Kit table).
|
||||||
|
- **Genetics** — per-rabbit loci (`A/B/C/D/E/En/V`) and a session-only pairing
|
||||||
|
calculator for predicting offspring.
|
||||||
|
- **Dashboard** — herd counts derived live from rabbit status.
|
||||||
|
- **Pedigree printing**, CSV import/export, and a configurable weight display
|
||||||
|
(decimal lbs or lb + oz).
|
||||||
|
- **PWA-ready** with a mobile bottom nav, installable on phones/tablets.
|
||||||
|
|
||||||
|
## Tech stack
|
||||||
|
|
||||||
|
| Layer | Choice |
|
||||||
|
| -------- | ----------------------------------------------------- |
|
||||||
|
| Frontend | React 19 + Vite (PWA-ready) |
|
||||||
|
| Routing | React Router v7 |
|
||||||
|
| State | React Query (server sync) |
|
||||||
|
| Styling | Tailwind CSS |
|
||||||
|
| Backend | Node.js + Express 5 (REST API) |
|
||||||
|
| Database | SQLite via Drizzle ORM (single-file DB) |
|
||||||
|
| Auth | Single-user session token (optional password) |
|
||||||
|
| Hosting | Docker Compose (Nginx + Node + SQLite volume) |
|
||||||
|
|
||||||
|
## Project layout
|
||||||
|
|
||||||
|
```
|
||||||
|
mykindlebox/
|
||||||
|
├── client/ React + Vite frontend
|
||||||
|
├── server/ Express + SQLite/Drizzle API
|
||||||
|
└── docker-compose.yml Production stack (nginx + node + volume)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Development
|
||||||
|
|
||||||
|
Run the backend and frontend in two terminals.
|
||||||
|
|
||||||
|
**Backend** (`server/`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd server
|
||||||
|
npm install
|
||||||
|
npm run dev # API on http://localhost:3001 (tsx watch, hot reload)
|
||||||
|
```
|
||||||
|
|
||||||
|
Other scripts: `npm run build` (typecheck + compile to `dist/`),
|
||||||
|
`npm start` (run compiled server), `npm test`.
|
||||||
|
|
||||||
|
**Frontend** (`client/`):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd client
|
||||||
|
npm install
|
||||||
|
npm run dev # Vite dev server on http://localhost:5173
|
||||||
|
```
|
||||||
|
|
||||||
|
The dev server proxies `/api` and `/uploads` to `localhost:3001`. Other
|
||||||
|
scripts: `npm run build`, `npm run lint`, `npm test`.
|
||||||
|
|
||||||
|
> The client talks to the API over **relative URLs** (`/api`, `/uploads`) so the
|
||||||
|
> app works over LAN and as an installed PWA — never hardcode a host.
|
||||||
|
|
||||||
|
## Deployment (Docker Compose)
|
||||||
|
|
||||||
|
From the `mykindlebox/` directory:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up --build
|
||||||
|
```
|
||||||
|
|
||||||
|
The app is served on **http://localhost:8080** — nginx serves the built client
|
||||||
|
and reverse-proxies `/api` + `/uploads` to the Node server. The SQLite database
|
||||||
|
and uploaded photos live in the `server-data` Docker volume.
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
Auth is **optional** and off by default. To require a login, set
|
||||||
|
`MYKINDLEBOX_PASSWORD` (e.g. in a `.env` file next to `docker-compose.yml`):
|
||||||
|
|
||||||
|
```env
|
||||||
|
MYKINDLEBOX_PASSWORD=your-password-here
|
||||||
|
```
|
||||||
|
|
||||||
|
If left unset, the app is open to anyone who can reach it — only acceptable on a
|
||||||
|
fully trusted network.
|
||||||
|
|
||||||
|
## Data & backups
|
||||||
|
|
||||||
|
The herd database (`server/data/`), uploaded photos, and `.env` files are
|
||||||
|
**gitignored** — they are never committed. In production they persist in the
|
||||||
|
`server-data` volume; back that volume up to preserve your data.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue