Archived
Marko (Hermes Implementer)
b8bd1dca14
- Backend: Django 5 + DRF with accounts, documents, collections, and reading apps - Custom User model with email-based auth, JWT via SimpleJWT - Full CRUD viewsets with ModelSerializer + DRF routers - pytest, Ruff, drf-spectacular (OpenAPI), whitenoise - Dockerfile for production deployment - Frontend: React 18 + TypeScript + Vite - Lazy-loaded routes with ProtectedRoute/PublicRoute guards - Auth context with useReducer, token refresh interceptor - Pages: Login, Register, Library, Document Detail, Reader, Collections, Settings - Dark theme, responsive grid layout, Vite proxy to Django backend - Mobile: Expo SDK 51 + React Native + Expo Router - File-based routing with login, register, and library screens - AsyncStorage for token persistence, token refresh interceptor - Shared API types via @cloud-reader/shared workspace package - Shared: TypeScript types (API responses, auth, documents, etc.) - CI/CD: 3 independent GitHub Actions pipelines (backend, frontend, mobile)
196 lines
5.2 KiB
Markdown
196 lines
5.2 KiB
Markdown
# 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)
|