PROJECT KNOWLEDGE BASE

Generated: 2026-04-23 Mode: init-deep (create-new)

OVERVIEW

Baby Sleep Tracker - self-hosted web app for tracking infant sleep. Dual-stack monorepo: React 19/Vite 6/TypeScript frontend + Python 3.14/FastAPI backend. Optimized for Raspberry Pi 4 (ARM64).

STRUCTURE

./
├── frontend/           # React 19 SPA
│   ├── src/
│   │   ├── api/      # React Query hooks
│   │   ├── components/
│   │   │   ├── stats/   # Charts, grids, trends (8 files - highest density)
│   │   │   └── tracker/ # Sleep session controls
│   │   ├── hooks/    # Custom React hooks
│   │   ├── types/    # TypeScript interfaces
│   │   └── utils/
│   └── tests/         # e2e (Playwright), unit (Vitest)
├── backend/           # FastAPI + SQLModel
│   ├── app/
│   │   ├── routers/   # API endpoints
│   │   └── utils/
│   └── tests/        # pytest + asyncio
└── docker-compose.yml

WHERE TO LOOK

Task	Location	Notes
Add sleep session	`backend/app/crud.py`	`create_session`, `update_session`
Fetch sleep data	`frontend/src/api/`	React Query hooks for sessions
UI components	`frontend/src/components/`	tracker/, stats/ subdirs
Backend models	`backend/app/models.py`	SQLModel definitions
API schemas	`backend/app/schemas.py`	Pydantic request/response

CONVENTIONS

Backend: SQLModel (not pure SQLAlchemy), async aiosqlite, pytest-asyncio
Frontend: React 19, TanStack Query v5, Tailwind v4, no ESLint config (yet)
Python: >=3.14 required, Hatch for packaging
Scripts: All scripts created in the backend folder must be placed in backend/scripts/.
No CI/CD: No .github/workflows, no Makefiles yet

ANTI-PATTERNS (THIS PROJECT)

No type suppression (as any, @ts-ignore, @ts-expect-error) - type safety enforced
No empty catch blocks - error handling required
No deleting failing tests to "pass"
Frontend JS Slop: NEVER create .js files for the frontend. Use only TypeScript (.ts, .tsx) and write high-quality, type-safe code. Do not repeat this mistake.
Assumption Error: NEVER assume the content of ANY files EVER. ALWAYS read the file to confirm. Do not rely on the name.

COMMANDS

# Backend
cd backend && uv sync
uv run uvicorn app.main:app --reload
uv run pytest

# Frontend
cd frontend && npm install
npm run dev
# Use 'npm test' with caution as it may hang; use specific test scripts instead.
npm run test

NOTES

Entry point: frontend/src/main.tsx + backend/app/main.py
DB: SQLite via aiosqlite (async-first backend)
Build: Docker for ARM64 Raspberry Pi deployment

2.7 KiB Raw Blame History