Fanfiction

A fanfiction platform powered by a Django REST backend and a Vue.js/Ionic frontend.

Table of contents

• Overview
• Features
• Architecture
• Requirements
• Quick start
  • Backend (Django)
  • Frontend (Vue.js/Ionic)
• Background tasks
• Translations
• Recommendation engine
• Scraper
• Testing
• Additional resources

Overview

This repository contains the source code for a bilingual fanfiction community. The Django backend exposes a REST API, background workers and administrative interfaces, while the Vue.js/Ionic application delivers the user-facing experience. Supporting utilities provide recommendations, content import and automated notifications.

A live demo of the mobile web application is available at fanfiction-fr.netlify.app.

Features

• Fanfiction catalogue with categories, tags, chapters, comments and user favourites.
• JWT/OAuth2-secured REST API built with Django REST Framework and Spectacular.
• Celery workers for scheduled notifications and account maintenance.
• Redis-backed recommendation engine based on user co-likes.
• Admin and moderation tooling for managing content and users.
• Internationalisation support and automated translation compilation.
• Modern stack targeting Django 5.1 and Python 3.12 deployments.

Architecture

├── backend/        # Django project configuration and Celery entrypoint
├── api/            # REST API endpoints, serializers and services
├── fanfics/        # Core fanfiction models, scraping utilities, recommendation engine
├── chapters/, comments/, categories/, helpcenter/, posts/, forum/  # Domain apps
├── templates/, static/   # Django templates and static assets
├── docs/           # Additional documentation and guidelines
└── frontend (Vue.js/Ionic)  # Separate project served from the same repository

Requirements

• Python 3.12+
• Node.js 16+ and npm
• Redis (for Celery/recommendations) – optional during development
• A PostgreSQL database in production (SQLite is used by default for local dev)

Environment Variables

The project includes an environment variable export script at /env/envs_export.sh that can be sourced on the VM or within Docker containers to set up all necessary environment variables. See env/README.md for detailed usage instructions.

Docker Deployment

When deploying with Docker, environment variables can be passed via --env-file or individually with -e. The entrypoint script automatically:

1. Sources /env/envs_export.sh if it exists
2. Executes an optional BUILD_COMMAND if set
3. Runs database migrations and collects static files

Example:

docker run -d --name fanfiction \
  -p 8000:8000 \
  --env-file /path/to/.env \
  -e BUILD_COMMAND="python manage.py custom_command" \
  --restart unless-stopped \
  fanfiction:latest

Quick start

Clone the repository and create the environment files (.env, .env.production, etc.) as needed. Example configuration for local development:

SECRET_KEY=change-me
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1
DATABASE_URL=sqlite:///db.sqlite3
EMAIL_BACKEND=django.core.mail.backends.console.EmailBackend
CELERY_BROKER_URL=redis://localhost:6379/0

Backend (Django)

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

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

# Apply migrations and create a superuser
python manage.py migrate
python manage.py createsuperuser

# Start the development server
python manage.py runserver

Frontend (Vue.js/Ionic)

cd frontend

# Install dependencies
npm install

# Serve with hot reload at http://localhost:8080
npm run dev

# Build for production
npm run build

# Build with bundle analysis report
npm run build --report

Background tasks

Celery workers power scheduled emails and periodic clean-up jobs. Run them alongside the web server after configuring the broker URL:

celery -A backend worker -l info
celery -A backend beat -l info

You can also combine worker and scheduler in a single process if required:

celery -A backend worker -l info -B

Translations

The project ships with localisation resources. To update message files and compile them:

# Extract new strings (ignoring the virtual environment directory)
django-admin makemessages --ignore=.venv/*

# Compile the message catalogues
django-admin compilemessages

Recommendation engine

The recommendation engine leverages Redis to track user likes and compute co-occurrence scores. You can experiment with it from the Django shell:

>>> from api.models import Fanfic
>>> from api.recommender import Recommender
>>> favourites = Fanfic.objects.filter(id__in=[1, 2])
>>> Recommender().suggest_fanfics_for(favourites)
[<Fanfic: Elementary>, <Fanfic: Nature>, ...]

Scraper

Import fanfiction content from external sources using the scraper utilities:

python manage.py import_from_fanfiction_as_csv output_ccs.csv
python manage.py import_from_fanfiction_as_csv output_op.csv
python manage.py import_from_fanfiction_as_csv output_marvel.csv

See fanfics/scraper.py for commands that generate these CSV files.

Testing

Run the test suite with coverage reporting:

coverage run --source=api --omit=*/migrations/* manage.py test
coverage report -m

For a quicker feedback loop you can also use Django's built-in test runner directly:

python manage.py test

Additional resources

• Django documentation
• Django REST Framework
• Celery task queue
• Vue.js guide
• Ionic documentation