cloud-reader/README.md

Cloud Reader

A modern eBook reader with web and mobile clients, powered by Django REST Framework.

Monorepo Structure

cloud-reader/
├── backend/            # Django API server (Python 3.12 + DRF)
│   ├── config/         # Django project settings
│   ├── apps/           # Django applications
│   │   ├── accounts/   # User authentication & profiles
│   │   ├── documents/  # Document management & uploads
│   │   ├── collections/# Document collections
│   │   └── reading/    # Bookmarks, highlights, reading progress
│   ├── requirements/   # pip dependency files
│   ├── Dockerfile
│   └── manage.py
├── frontend/           # React web app (TypeScript + Vite)
│   ├── src/
│   │   ├── pages/      # Route pages (lazy-loaded)
│   │   ├── hooks/      # Custom React hooks
│   │   ├── services/   # API client & auth service
│   │   ├── types/      # Frontend-specific types
│   │   └── styles/     # Global CSS
│   ├── Dockerfile
│   └── vite.config.ts
├── mobile/             # Expo/React Native mobile app
│   ├── app/            # Expo Router pages
│   ├── src/            # Mobile source code
│   ├── app.json
│   └── Dockerfile
├── shared/             # Shared TypeScript types & utilities
│   └── src/
│       └── index.ts    # API response types, constants
├── .github/workflows/  # CI/CD pipelines
└── package.json        # Yarn workspace root

Prerequisites

• Python 3.12+
• Node.js 20 LTS
• Yarn 4.x
• PostgreSQL 16
• Expo CLI (for mobile development)

---

Backend Setup

cd backend

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements/dev.txt

# Configure environment
cp .env.example .env
# Edit .env with your PostgreSQL credentials

# Run migrations
python manage.py migrate

# Create admin user
python manage.py createsuperuser

# Start development server
python manage.py runserver

The API will be available at http://localhost:8000/. Browse the API at http://localhost:8000/api/schema/swagger-ui/.

Backend Tests

cd backend
pytest

---

Frontend Setup

# From monorepo root
yarn install

# Start dev server (with API proxy)
yarn frontend:dev

The frontend will be available at http://localhost:5173/. API requests under /api/ are proxied to http://localhost:8000/.

Frontend Build

yarn frontend:build

---

Mobile Setup

# From monorepo root
yarn install

# Start Expo dev server
yarn mobile:start

# Run on Android
yarn mobile:android

# Run on iOS (macOS only)
yarn mobile:ios

The mobile API client defaults to http://localhost:8000/. For physical devices, update the API_BASE in mobile/src/services/api.ts to your machine's local IP.

---

Shared Package

The shared/ package contains TypeScript types and constants used by both the frontend and mobile apps.

# Build shared package
yarn shared:build

---

CI/CD

Three independent CI pipelines run on pushes and PRs:

Pipeline	Trigger Path	What It Does
Backend CI	backend/**	Installs Python deps, runs Ruff linter, applies migrations, runs pytest
Frontend CI	frontend/**, shared/**	Installs Node deps, type-check & build shared, type-check & build frontend
Mobile CI	mobile/**, shared/**	Installs Node deps, type-check shared & mobile

Pipeline configs are in .github/workflows/.

Docker Deployments

Each app has its own Dockerfile for independent deployment:

# Build backend image
docker build -t cloud-reader-backend backend/

# Build frontend image
docker build -t cloud-reader-frontend frontend/

# Build mobile image (web export)
docker build -t cloud-reader-mobile mobile/

---

API Endpoints

Endpoint	Description
POST /api/v1/auth/register/	Create a new account
POST /api/v1/auth/token/	Obtain JWT tokens
POST /api/v1/auth/token/refresh/	Refresh JWT token
GET /api/v1/auth/me/	Get current user profile
GET/POST /api/v1/documents/	List / upload documents
GET/PUT/DELETE /api/v1/documents/:id/	Document detail
GET/POST /api/v1/collections/	List / create collections
GET/PUT/DELETE /api/v1/collections/:id/	Collection detail
POST /api/v1/collections/:id/add_documents/	Add docs to collection
POST /api/v1/collections/:id/remove_documents/	Remove docs from collection
GET/POST /api/v1/reading/bookmarks/	List / create bookmarks
GET/POST /api/v1/reading/highlights/	List / create highlights
GET/POST /api/v1/reading/progress/	Track reading progress

---

Tech Stack

• Backend: Django 5, Django REST Framework, SimpleJWT, PostgreSQL, drf-spectacular
• Frontend: React 18, TypeScript, Vite, React Router, Axios
• Mobile: Expo SDK 51, React Native 0.74, Expo Router
• Shared: TypeScript types, Zod schemas
• CI/CD: GitHub Actions
• Container: Docker (separate images per app)