Parallel Reading

A platform for parallel reading of books in foreign languages with an integrated dictionary and flashcard system

Table of Contents

• Architecture
  • Services
  • Infrastructure
  • Spring profiles
• Quick Start using Docker Compose
• Prod deployment

Architecture

Services

The system consists of the following microservices:

1. Book Service - manages books, chapters, and pages
2. Translation Service - translates words via the Yandex Dictionary API. Using StanfordNLP for lemmatization
3. Dictionary Service - manages user flashcards and vocabulary, implements the SuperMemo 2 algorithm for interval repetition
4. Book Upload Service - parses book texts using Apache OpenNLP
5. Auth Service - user registration, password reset, etc
6. Admin Client - web interface for administrators

Frontend app (Vue.js 3, Typescript, Vite, TailWind): https://github.com/TVFK/parallel-reading-frontend

Infrastructure

1. PostgreSQL - main data storage
2. Redis - caching frequently requested data
3. Kafka - asynchronous communication
4. MinIO - stores book covers and texts
5. Keycloak - OAuth 2.0/OIDC authentication
6. Nginx - reverse proxy and static content distribution
7. Victoria Metrics - collection of metrics
8. Grafana Loki - log collection
9. Grafana Tempo - collecting traces
10. Grafana - visualization of metrics, logs and traces

Spring profiles

1. standalone - for local Spring services startup without Docker
2. docker - local startup of all services without HTTPS, nginx, monitoring etc.
3. prod - for production deployment

Quick Start using Docker Compose

The entire application can be run locally using the compose.yaml file, all services will be deployed on localhost

1. Clone the repository

git clone https://github.com/TVFK/parallel-reading.git

2. project collection

mvn clean package -DskipTests

3. Start all services

docker compose up -d --build

The application will be available at: http://localhost

admin console: http://localhost:8083

MinIO console: http://localhost:9090

Keycloak console: http://localhost:8082

Environment variables

Translation service requires:

YANDEX_DICT_API_KEY=your_yandex_dictionary_key

API key for Yandex Dictionary can be obtained at https://yandex.ru/dev/dictionary/

Prod deployment

1. Clone the repository

git clone https://github.com/TVFK/parallel-reading.git

2. Creating Environment variables

In the root of the project next to compose.prod.yaml it is necessary to create a .env file with these variables:

BASE_URL=
DOMAIN=

# Keycloak variables
KEYCLOAK_DB_PASSWORD=
KEYCLOAK_ADMIN_LOGIN=
KEYCLOAK_ADMIN_PASSWORD=

# Minio variables
MINIO_ROOT_USER=
MINIO_ROOT_PASSWORD=

# Services db
BOOKS_DB_PASSWORD=
DICTIONARY_DB_PASSWORD=

# Services cache
BOOKS_SERVICE_CACHE_PASSWORD=
TRANSLATION_SERVICE_CACHE_PASSWORD=

GRAFANA_ADMIN_PASSWORD=

YANDEX_DICT_API_KEY=

3. Building Spring Services

mvn clean package -DskipTests

4. Configuring nginx

In the config/nginx/prod/nginx-prod.conf file, you need to change the domain to your own

5. Obtaining a TLS certificate

To work with HTTPS you need to get certificates. You can do this using [certbot](https://certbot.eff.org /)

6. Starting compose.prod.yaml

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