ReadNovls

A modern open-source platform for reading and writing novels, stories, and serialized fiction. Built with NestJS, SvelteKit, and PostgreSQL.

About

ReadNovls is a full-featured platform similar to Wattpad or Royal Road, where authors can publish their stories chapter by chapter, and readers can discover, read, and engage with content through likes, views, and comments.

Features

User Management
- Email/password authentication
- Google OAuth integration
- JWT-based session management
- User profiles and account management
Story Management
- Create single stories or multi-part series
- Rich text editor with TipTap
- Draft and publish functionality
- Cover image uploads with Cloudinary
- Genre and tag categorization
- Mature content flagging
- Featured stories
Reader Engagement
- Like and view tracking with rate limiting
- Comment system
- Story discovery and search
- Responsive reading experience
Admin Features
- Content moderation
- User management
- Featured story curation
- Analytics dashboard
Infrastructure
- Background job processing with BullMQ
- Redis caching
- Email notifications
- Full-text search
- RESTful API with Swagger documentation
- Health checks and monitoring

Tech Stack

Backend (API)

Framework: NestJS 11
Database: PostgreSQL 16 with TypeORM
Cache/Queue: Redis 7 with BullMQ
Authentication: Passport.js with JWT
Email: Resend / Nodemailer
File Upload: Cloudinary
Security: Helmet, CSRF protection, rate limiting
Logging: Pino
API Docs: Swagger/OpenAPI

Frontend (Web & Admin)

Framework: SvelteKit 2 with Svelte 5
Styling: TailwindCSS 4
UI Components: Bits UI
Rich Text: TipTap
Forms: Formsnap with Zod validation
HTTP Client: Axios
Testing: Vitest, Playwright

Infrastructure

Containerization: Docker with Docker Compose
Package Manager: pnpm workspaces
Language: TypeScript

Architecture

This is a pnpm workspace monorepo with the following structure:

aaccraa/
├── apps/
│   ├── api/          # NestJS REST API
│   ├── web/          # SvelteKit web application
│   └── admin/        # SvelteKit admin panel
└── packages/         # Shared packages (future)

API Architecture

The API follows NestJS best practices with a modular architecture:

src/modules/ - Feature modules (auth, users, stories, etc.)
src/common/ - Shared utilities, decorators, filters, interceptors
src/core/ - Core functionality (database, docs, mail, queue, redis, security)
src/providers/ - External service integrations (Cloudinary, AutoSend)

Path aliases are configured for clean imports:

@/modules/* → src/modules/*
@/common/* → src/common/*
@/core/* → src/core/*
@/providers/* → src/providers/*

Frontend Architecture

Both web and admin apps follow a similar structure:

src/lib/ - Shared components, utilities, types, hooks
src/modules/ - Feature-specific components and logic
src/routes/ - SvelteKit file-based routing with route groups
src/services/ - API service layer
src/styles/ - Global styles

Getting Started

Prerequisites

Node.js >= 20.0.0
pnpm >= 9.0.0
Docker and Docker Compose (for database and Redis)
PostgreSQL 16+ (if not using Docker)
Redis 7+ (if not using Docker)

Installation

Clone the repository

git clone https://github.com/yourusername/aaccraa.git
cd aaccraa

Install dependencies
```
pnpm install
```

Environment Configuration

1. API Environment Setup

Copy the example environment file:

cp apps/api/.env.example apps/api/.env

Edit apps/api/.env and configure:

Required:

# Server
PORT=3002
FRONTEND_URL=http://localhost:5173

# JWT Secrets (generate with: node -e "console.log(require('crypto').randomBytes(64).toString('hex'))")
JWT_SECRET=your-strong-secret-here
JWT_REFRESH_SECRET=your-different-strong-secret-here
CSRF_SECRET=your-csrf-secret-here
ANONYMOUS_VIEW_SECRET=your-view-secret-here

# Database
DB_HOST=localhost
DB_PORT=5433
DB_USER=aaccraa
DB_PASSWORD=your-secure-password
DB_NAME=aaccraa

# Redis
REDIS_HOST=localhost
REDIS_PORT=6380
REDIS_PASSWORD=your-secure-redis-password

# Email (AutoSend or other provider)
AUTOSEND_API_KEY=your-api-key
MAIL_FROM=noreply@yourdomain.com

Optional:

# Google OAuth (for social login)
GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_CALLBACK_URL=http://localhost:3002/api/v1/auth/google/callback

2. Web Environment Setup

cp apps/web/.env.example apps/web/.env

Edit apps/web/.env:

PUBLIC_API_URL=http://localhost:3002

3. Admin Environment Setup

cp apps/admin/.env.example apps/admin/.env

Edit apps/admin/.env:

PUBLIC_API_URL=http://localhost:3002

Database Setup

Option 1: Using Docker (Recommended)

Start PostgreSQL and Redis with Docker Compose:

cd apps/api
docker-compose up -d

This starts:

PostgreSQL on port 5433
Redis on port 6380

Option 2: Local Installation

Install PostgreSQL 16+ and Redis 7+ locally and update the connection details in your .env file.

Run Migrations

cd apps/api
pnpm build
pnpm migration:run

Seed Database (Optional)

pnpm seed

Development

Run All Services

From the root directory:

pnpm dev

This starts:

Run Individual Services

# API only
pnpm dev:api

# Web only
pnpm dev:web

# Admin only
pnpm dev:admin

API Documentation

When the API is running, access Swagger documentation at:

http://localhost:3002/api/docs

Health Check

http://localhost:3002/api/v1/health

Testing

Run All Tests

pnpm test

API Tests

cd apps/api
pnpm test           # Unit tests
pnpm test:watch     # Watch mode
pnpm test:cov       # Coverage report
pnpm test:e2e       # E2E tests

Web Tests

cd apps/web
pnpm test:unit      # Unit tests
pnpm test:e2e       # Playwright E2E tests

Admin Tests

cd apps/admin
pnpm test:unit      # Unit tests
pnpm test:e2e       # Playwright E2E tests

Deployment

Production Build

pnpm build

Docker Deployment

Configure production environment

cp .env.production.example .env.production

Edit .env.production with production values:
- Generate strong secrets for JWT tokens
- Set strong database passwords
- Configure your domain for FRONTEND_URL
- Set up email service credentials

Build and deploy

docker-compose -f docker-compose.prod.yml up -d --build

This starts:

PostgreSQL (internal only)
Redis (internal only)
API on port 3002
Web on port 3000

Run Production Migrations

docker exec -it readnovls-api-prod pnpm migration:run:prod

Viewing Logs

# View all logs
docker-compose -f docker-compose.prod.yml logs -f

# View specific service logs
docker-compose -f docker-compose.prod.yml logs -f api
docker-compose -f docker-compose.prod.yml logs -f web

Project Structure

aaccraa/
├── apps/
│   ├── api/                    # NestJS Backend
│   │   ├── src/
│   │   │   ├── common/         # Shared utilities
│   │   │   │   ├── decorators/ # Custom decorators
│   │   │   │   ├── entities/   # Base entities
│   │   │   │   ├── filters/    # Exception filters
│   │   │   │   ├── interceptors/
│   │   │   │   ├── middleware/
│   │   │   │   └── utils/
│   │   │   ├── core/           # Core functionality
│   │   │   │   ├── config/     # Configuration
│   │   │   │   ├── database/   # TypeORM & migrations
│   │   │   │   ├── docs/       # Swagger setup
│   │   │   │   ├── health/     # Health checks
│   │   │   │   ├── logger/     # Pino logger
│   │   │   │   ├── mail/       # Email service
│   │   │   │   ├── queue/      # BullMQ jobs
│   │   │   │   ├── redis/      # Redis client
│   │   │   │   ├── scheduler/  # Cron jobs
│   │   │   │   └── security/   # Security config
│   │   │   ├── modules/        # Feature modules
│   │   │   │   ├── accounts/   # Account management
│   │   │   │   ├── admin/      # Admin features
│   │   │   │   ├── auth/       # Authentication
│   │   │   │   ├── comments/   # Comment system
│   │   │   │   ├── profile/    # User profiles
│   │   │   │   ├── stories/    # Story management
│   │   │   │   │   ├── dto/
│   │   │   │   │   ├── entities/
│   │   │   │   │   └── services/
│   │   │   │   ├── upload/     # File uploads
│   │   │   │   └── users/      # User management
│   │   │   ├── providers/      # External services
│   │   │   │   ├── autosend/   # Email provider
│   │   │   │   └── cloudinary/ # Image hosting
│   │   │   └── main.ts         # Application entry
│   │   ├── test/               # E2E tests
│   │   ├── .env.example
│   │   ├── docker-compose.yml
│   │   └── package.json
│   │
│   ├── web/                    # SvelteKit Web App
│   │   ├── src/
│   │   │   ├── lib/            # Shared code
│   │   │   │   ├── assets/     # Images, fonts, etc.
│   │   │   │   ├── axios/      # Axios config
│   │   │   │   ├── components/ # Reusable components
│   │   │   │   ├── hooks/      # Custom hooks
│   │   │   │   ├── types/      # TypeScript types
│   │   │   │   └── utils/      # Utility functions
│   │   │   ├── modules/        # Feature modules
│   │   │   │   ├── auth/       # Auth components
│   │   │   │   ├── comments/   # Comment components
│   │   │   │   ├── profile/    # Profile components
│   │   │   │   └── stories/    # Story components
│   │   │   ├── routes/         # SvelteKit routes
│   │   │   │   ├── (auth)/     # Auth route group
│   │   │   │   ├── (system)/   # Public routes
│   │   │   │   └── sitemap.xml/
│   │   │   ├── services/       # API services
│   │   │   │   ├── auth/
│   │   │   │   ├── comments/
│   │   │   │   ├── stories/
│   │   │   │   └── upload/
│   │   │   └── styles/         # Global styles
│   │   ├── static/             # Static assets
│   │   ├── .env.example
│   │   └── package.json
│   │
│   └── admin/                  # SvelteKit Admin Panel
│       ├── src/
│       │   ├── lib/            # Shared code
│       │   │   ├── assets/
│       │   │   ├── axios/
│       │   │   ├── components/
│       │   │   ├── hooks/
│       │   │   ├── types/
│       │   │   └── utils/
│       │   ├── modules/        # Feature modules
│       │   │   └── auth/
│       │   ├── routes/         # SvelteKit routes
│       │   │   ├── (admin)/    # Admin route group
│       │   │   └── (auth)/     # Auth route group
│       │   ├── services/       # API services
│       │   │   ├── analytics/
│       │   │   ├── auth/
│       │   │   ├── stories/
│       │   │   └── users/
│       │   └── styles/         # Global styles
│       ├── static/
│       ├── .env.example
│       └── package.json
│
├── packages/                   # Shared packages (future)
├── docker-compose.prod.yml     # Production deployment
├── .env.production.example
├── pnpm-workspace.yaml
├── package.json
└── README.md

API Documentation

Authentication Endpoints

POST   /api/v1/auth/register
POST   /api/v1/auth/login
POST   /api/v1/auth/refresh
POST   /api/v1/auth/logout
GET    /api/v1/auth/google
GET    /api/v1/auth/google/callback

Story Endpoints

GET    /api/v1/stories
GET    /api/v1/stories/:id
POST   /api/v1/stories
PUT    /api/v1/stories/:id
DELETE /api/v1/stories/:id
POST   /api/v1/stories/:id/publish
POST   /api/v1/stories/:id/like
POST   /api/v1/stories/:id/view

User Endpoints

GET    /api/v1/users/me
PUT    /api/v1/users/me
GET    /api/v1/users/:id

For complete API documentation, run the API and visit /api/docs.

Available Scripts

Root Level

pnpm dev              # Run API and web in parallel
pnpm dev:api          # Run API only
pnpm dev:web          # Run web only
pnpm dev:admin        # Run admin only
pnpm build            # Build all packages
pnpm test             # Run tests in all packages
pnpm lint             # Lint all packages
pnpm format           # Format code with Prettier

API Scripts

pnpm build            # Build the application
pnpm dev              # Start in watch mode
pnpm start:prod       # Start production build
pnpm test             # Run unit tests
pnpm test:e2e         # Run E2E tests
pnpm lint             # Lint and fix
pnpm migration:generate  # Generate new migration
pnpm migration:run    # Run migrations
pnpm migration:revert # Revert last migration
pnpm seed             # Seed database

Web/Admin Scripts

pnpm dev              # Start dev server
pnpm build            # Build for production
pnpm preview          # Preview production build
pnpm test:unit        # Run unit tests
pnpm test:e2e         # Run E2E tests
pnpm check            # Type-check
pnpm lint             # Lint code
pnpm format           # Format code

Database Migrations

Create a New Migration

After modifying entities:

cd apps/api
pnpm migration:generate src/core/database/migrations/YourMigrationName

Run Migrations

pnpm migration:run

Revert Last Migration

pnpm migration:revert

View Migration Status

pnpm migration:show

Contributing

We welcome contributions! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Contribution Guidelines

Follow the existing code style
Write tests for new features
Update documentation as needed
Use conventional commits (feat, fix, docs, style, refactor, test, chore)
Ensure all tests pass before submitting PR
Keep PRs focused on a single feature or fix

Code Style

TypeScript: Use TypeScript for all new code
ESLint & Prettier: Follow the configured linting and formatting rules
Path Aliases: Use path aliases for imports in the API (@/modules/*, @/common/*, etc.)
Naming Conventions: Use descriptive variable and function names
Comments: Add JSDoc comments for public APIs and complex logic

Reporting Issues

Use the GitHub issue tracker
Check if the issue already exists
Provide a clear description and steps to reproduce
Include relevant logs or screenshots
Specify your environment (OS, Node version, etc.)

Development Workflow

Create a new branch from master
Make your changes
Run tests locally: pnpm test
Run linting: pnpm lint
Format code: pnpm format
Commit with conventional commit messages
Push and create a PR

Security

If you discover a security vulnerability, please email security@readnovls.com instead of using the issue tracker.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with NestJS
Frontend powered by SvelteKit
UI components from Bits UI
Rich text editing with TipTap

Support

Documentation: [Link to docs site]
Discord: [Link to Discord]
Email: support@readnovls.com

Made with ❤️ by the ReadNovls community

Name		Name	Last commit message	Last commit date
Latest commit History 126 Commits
apps		apps
.env.production.example		.env.production.example
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
Dockerfile.admin		Dockerfile.admin
Dockerfile.web		Dockerfile.web
README.md		README.md
docker-compose.prod.yml		docker-compose.prod.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json

Folders and files

Latest commit

History

Repository files navigation

ReadNovls

Table of Contents

About

Features

Tech Stack

Backend (API)

Frontend (Web & Admin)

Infrastructure

Architecture

API Architecture

Frontend Architecture

Getting Started

Prerequisites

Installation

Environment Configuration

1. API Environment Setup

2. Web Environment Setup

3. Admin Environment Setup

Database Setup

Option 1: Using Docker (Recommended)

Option 2: Local Installation

Run Migrations

Seed Database (Optional)

Development

Run All Services

Run Individual Services

API Documentation

Health Check

Testing

Run All Tests

API Tests

Web Tests

Admin Tests

Deployment

Production Build

Docker Deployment

Run Production Migrations

Viewing Logs

Project Structure

API Documentation

Authentication Endpoints

Story Endpoints

User Endpoints

Available Scripts

Root Level

API Scripts

Web/Admin Scripts

Database Migrations

Create a New Migration

Run Migrations

Revert Last Migration

View Migration Status

Contributing

Contribution Guidelines

Code Style

Reporting Issues

Development Workflow

Security

License

Acknowledgments

Support

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages