Archived
crisleo94
6b4c0c43f8
- add uv configuration for the backend - update frontend to make auth work - add new auth endpoints - add bookmars feat - add reader feat
106 lines
4.4 KiB
Markdown
106 lines
4.4 KiB
Markdown
# 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
|
|
```
|