# PROJECT BABY MONITOR

## OVERVIEW

Baby monitor - 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
│   ├── scripts/       # one-off scripts for migrations / fixes / etc
│   ├── 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. Managed via `uv` with Hatch backend for packaging.
- **Scripts**: All scripts created in the backend folder must be placed explicitly in `backend/scripts/`.
- **CI/CD**: Deployment is managed via Gitea workflows (`.gitea/` directory). Do not create `.github/` directories or Makefiles.

## ANTI-PATTERNS (CRITICAL GUARDRAILS)

- **Type Safety**: No type suppression (`as any`, `@ts-ignore`, `@ts-expect-error`). Type safety is strictly enforced.
- **Error Handling**: No empty catch blocks. Explicit error handling/logging is required.
- **Testing Integrity**: NEVER delete or comment out failing tests to make a suite "pass". Fix the code or update the test properly.
- **Frontend JS Slop**: NEVER create `.js` or `.jsx` files for the frontend. Use only TypeScript (`.ts`, `.tsx`). Write clean, type-safe code.
- **Assumption Error**: NEVER assume the content of ANY files. ALWAYS read the target file to confirm its structure and implementation before modifying or referencing it.

## COMMANDS

### Backend Development

```bash
cd backend
uv sync
uv run uvicorn app.main:app --reload
uv run pytest
```

### Frontend Development

```bash
cd frontend
npm install
npm run dev

# WARNING: 'npm test' may hang if run globally. Use specific file paths or vitest flags.
npm run test
```

## 🛑 DIRECTORY NAVIGATION & FILE DISCOVERY

**Context:** This is a full-stack monorepo containing massive generated/dependency folders (`node_modules`, `dist`, `venv`, `.venv`, `__pycache__`, etc.). Unrestricted file listings will bloat your context window, crash your session, and cause severe token waste.

* **NEVER use `ls -R`:** This command is strictly forbidden in this repository.
* **Primary Discovery:** To map out files or explore the project tree, **ALWAYS use `git ls-files**`. This is your default command and ensures you only interact with human-written source code.
* **Structural Context:** If you explicitly need a visual directory layout to understand architecture, use `tree` appended with the mandatory ignore flags:
```bash
tree -I 'node_modules|.git|dist|build|__pycache__|venv|.venv|env|.pytest_cache|.mypy_cache|.ruff_cache|*.egg-info'

```


* **Searching Code:** If you need to search for text or code blocks across the repo, **ALWAYS use `git grep "search_term"**` instead of standard `grep -r` to avoid crawling ignored or minified assets.

## 🧠 TASK DELEGATION & CONTEXT PRESERVATION

**Context:** The main OpenCode agent context window is our most critical resource. Executing complex tasks, debugging cross-file issues, or writing massive features directly in the main thread causes severe context bloat, leading to code hallucinations and dropped instructions.

* **Delegate Aggressively:** For any complex implementation, structural change, or task larger than a single file edit, you **MUST spawn a sub-agent**. Act strictly as the architectural orchestrator; let sub-agents handle the iterative coding labor.
* **Scope Narrowly:** Give sub-agents highly specific, isolated, and atomic objectives (e.g., *"Read `backend/app/routers/auth.py` and summarize endpoints"* or *"Write a unit test for the frontend sleep tracker component"*).
* **Strict Summarization:** Sub-agents are **STRICTLY FORBIDDEN** from passing raw terminal dumps, unedited file blocks, or their internal step-by-step logs back to the main thread.
* **Return Format:** Sub-agents must return *only* clear, actionable results back to the orchestrator: a concise summary of findings, the exact lines of code that require modification, or direct confirmation of a successful execution.

## NOTES

* **Entry Points:** `frontend/src/main.tsx` (Frontend) & `backend/app/main.py` (Backend).
* **Database:** Local SQLite managed via `aiosqlite` for an entirely async-first data layer.
* **Target Architecture:** Built specifically for ARM64 deployment on a Raspberry Pi 4 via Docker.