cloud-reader/README.md

Cloud Reader

A full-stack e-book reader application with cross-device sync. Upload EPUB/PDF files, track reading progress, bookmark passages, take notes, and customize your reading experience.

Architecture

cloud-reader/
├── backend/         # Django REST API (canonical backend)
│   ├── config/      # Django project settings
│   ├── apps/
│   │   ├── users/       # User auth (JWT)
│   │   ├── books/       # Books, e-books, reading progress, settings
│   │   └── annotations/ # Bookmarks and notes
│   ├── manage.py
│   └── requirements.txt
├── frontend/        # React + Vite + TypeScript (web frontend)
│   ├── src/
│   │   ├── api/         # API client (axios with JWT refresh)
│   │   ├── components/  # Reusable components
│   │   ├── context/     # Auth and annotations context
│   │   ├── hooks/       # Custom hooks
│   │   ├── pages/       # Route pages (Library, Reader, AddBook, Auth, Settings)
│   │   └── types/       # TypeScript type definitions
│   └── package.json
├── mobile/          # Expo React Native app (mobile frontend)
│   ├── src/
│   │   ├── api/         # API client (axios with JWT refresh via AsyncStorage)
│   │   ├── components/  # Reusable UI components
│   │   ├── context/     # Auth context
│   │   ├── hooks/       # Custom hooks
│   │   ├── navigation/  # React Navigation (Auth stack + Main tabs)
│   │   ├── screens/     # Screen-level components (Login, Library, etc.)
│   │   └── types/       # Mobile-specific types
│   ├── App.tsx
│   └── app.json
├── packages/
│   └── shared/       # @cloud-reader/shared — domain types & utilities
│       └── src/
│           ├── types.ts   # Shared domain types (Book, User, Bookmark, Note, etc.)
│           └── utils.ts   # Date formatting, validation, API endpoint constants
├── package.json      # Root — yarn workspaces config
└── docker-compose.yml

Quick Start

Docker (recommended)

cp env.example .env

docker compose up --build

• Frontend: http://localhost:5173
• Backend API: http://localhost:8000/api/

Backend (standalone)

cd backend
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

Frontend (standalone)

cd frontend
yarn install
yarn dev

Mobile (Expo)

# From monorepo root — installs all workspaces including mobile
yarn install

# Start Expo dev server
yarn workspace @cloud-reader/mobile start

# Or cd into mobile and run directly
cd mobile
npx expo start

The mobile app requires the backend to be running. Set EXPO_PUBLIC_API_URL environment variable in your shell or .env file to point to the backend (defaults to http://10.0.2.2:8000 for Android emulator).

Migration Notes

Consolidated from duplicate api/ + web/ into single backend/ + frontend/ canonical structure.

• backend/ kept as canonical; api/ features (e-book uploads, reading progress, reading settings) merged in.
• frontend/ kept as canonical; web/ pages (Library, Reader, AddBook, Auth, Settings) merged in.
• api/ and web/ directories removed.
• mobile/ added as Expo React Native app with shared @cloud-reader/shared package.