# 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
- **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"

## COMMANDS

```bash
# 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