# 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

```bash
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

```bash
cd backend
pytest
```

---

## Frontend Setup

```bash
# 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

```bash
yarn frontend:build
```

---

## Mobile Setup

```bash
# 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.

```bash
# 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:

```bash
# 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)