cloud-reader/AGENTS.md

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 EBooks.
• 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)

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

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