# AGENTS.md — Cloud Reader monorepo

Guidance for AI agents and contributors working in this repository.

## Repository layout

```
cloud-reader/
├── backend/          # Django REST API (canonical backend)
├── frontend/         # React + Vite + TypeScript (web)
├── mobile/           # Expo React Native app
├── packages/shared/  # @cloud-reader/shared types & utils
├── docs/             # Feature specs and architecture notes
└── docker-compose.yml
```

- **Backend** is the source of truth for API contracts, auth, and persistence.
- **Frontend** and **mobile** consume the same REST API; share domain types via `@cloud-reader/shared` where practical.
- Do not reintroduce removed `api/` or `web/` directories.

## Documentation conventions

| Location | Purpose |
|----------|---------|
| `docs/NNN-*.md` | Cross-cutting or product specs (e.g. `001-customizable-mobile-reading-experience.md`) |
| `docs/backend/NNN-*.md` | Backend feature specs; use next sequential number (currently `010`) |
| `docs/mobile/NNN-*.md` | Mobile (Expo) feature specs; use next sequential number (currently `010`) |
| `docs/frontend/*.md` | Frontend-specific specs |

When adding a **major backend feature**:

1. Implement in `backend/apps/<app>/`.
2. Add or update a numbered spec under `docs/backend/`.
3. Include: objective, API contracts, models/services touched, env vars, and verification steps.

Do not edit plan files in `.cursor/plans/` unless explicitly asked.

## Backend (Django)

- **Python:** 3.12+, managed with `uv` (`backend/pyproject.toml`, `backend/uv.lock`).
- **Settings:** `backend/config/settings.py` (pydantic-settings) + `backend/config/django.py`.
- **Apps:** `users`, `books`, `annotations`, `reader`.
- **Auth:** JWT via `djangorestframework-simplejwt`; register/login at `/api/auth/`.
- **Default permission:** `IsAuthenticated` — public endpoints must set `AllowAny` explicitly.
- **URL routing:** Single `DefaultRouter` in `books/urls.py`; register specific prefixes (e.g. `ebooks`) **before** the empty `""` book route to avoid `{pk}` shadowing.
- **Services:** Put non-trivial logic in `apps/<app>/services/` (not in views/serializers).
- **Migrations:** Run after model changes; prefer reusing existing JSON fields (e.g. `EBook.metadata_json`) before new columns.
- **Tests:** Only add when requested or when they cover non-obvious behavior.

### Books domain

- **`Book`:** Catalog/discovery entity (genres, reading status).
- **`EBook`:** Per-user uploaded file (EPUB/PDF); primary import path via `POST /api/books/ebooks/`.
- **`metadata_json` on EBook:** External metadata (Open Library, etc.).
- **`cover_image` on EBook:** Stored file; library UI reads it from list/detail serializers.

## Frontend (web)

- **Entry:** `frontend/src/main.tsx` mounts `App.tsx` (React Router + auth).
- **API client:** `frontend/src/api/client.ts` (axios, JWT refresh, base URL `/api`).
- **Auth routes:** `/auth` (not `/login`).
- **Imports:** Upload via `booksApi.uploadEBook`; library lists user `EBook`s.
- **Styling:** Mix of inline styles and CSS modules; match surrounding patterns.
- Do not add tests or new `.md` files unless requested.

## Mobile (Expo)

- Uses `@cloud-reader/shared` and mirrors web API patterns.
- Token storage: AsyncStorage; base URL from `EXPO_PUBLIC_API_URL`.

## Shared package

- `packages/shared/src/types.ts` — domain types for web/mobile.
- `packages/shared/src/utils.ts` — API endpoint constants, helpers.
- Keep camelCase in TS; backend JSON may use snake_case (DRF default).

## Code change principles

1. **Minimize scope** — smallest correct diff; no drive-by refactors.
2. **Match conventions** — read neighboring code before adding new patterns.
3. **No over-engineering** — no extra abstractions for one-off use.
4. **Comments** — only for non-obvious business logic.
5. **Imports** — remove unused imports; delete dead code after refactors.
6. **Secrets** — never commit `.env`; document vars in `.env.example` only.

## Git & PRs

- Commit only when the user asks.
- Do not force-push `main`/`master`.
- Use `gh` for GitHub PRs when requested.

## Postman

- Use camelCase operation names (`listSomething`, `createSomething`).
- Ask which env vars the user uses; output JSON to copy, not a new file.

## Commands (run locally when needed)

```bash
# Backend
cd backend && uv sync && uv run python manage.py migrate && uv run python manage.py runserver

# Frontend
cd frontend && yarn install && yarn dev
```