Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/aliammari1/readrealm/llms.txt

Use this file to discover all available pages before exploring further.

ReadRealm uses a three-tier architecture: client applications communicate with a single NestJS backend API, which in turn manages a MongoDB database and a set of external AI and speech services.

​
Application roles

AppTypeTechnologyPurposeUsers
APIBackendNestJS + TypeScriptServes all clients, manages data and AIAll clients
AndroidClientKotlin + Jetpack ComposeNative mobile reading appEnd users
iOSClientSwiftNative mobile reading appEnd users
DashboardAdminFlutter (Web / Desktop / macOS)Management, analytics, moderationAdministrators

​
Backend modules

The NestJS API is organized into focused modules. The root AppModule (apps/api/src/app.module.ts) imports all of them and applies a global LoggerMiddleware to every route.
ModulePurposeKey technologies
authUser authentication and authorizationJWT, bcrypt
bookBook library management and EPUB parsingMongoose, pdf-lib
chatReal-time conversationsSocket.IO, NestJS Gateways
userUser profile management and preferencesMongoDB, Mongoose
verificationEmail verification and OTP workflowsNodeMailer, Crypto
speech-realtimeVoice processing and audio narrationFFmpeg, Azure Cognitive Services
The AppModule registers ConfigModule, JwtModule, and MongooseModule globally, so all feature modules share a single database connection and JWT configuration.

​
Communication patterns

​
REST API (CRUD operations)

All four applications — Android, iOS, Flutter dashboard, and any future client — communicate with the NestJS API over HTTP REST for standard create, read, update, and delete operations. The full endpoint specification is defined in shared/api-spec/openapi.yaml. The API listens on port 3000 by default, configurable via the PORT environment variable: 
await app.listen(process.env.PORT ?? 3000);
CORS is enabled for all origins to support web-based clients: 
app.enableCors({ origin: '*' });
The JSON body size limit is set to 100 MB to accommodate EPUB file uploads: 
app.use(json({ limit: '100mb' }));

​
WebSocket (real-time chat)

The ChatModule uses Socket.IO and NestJS WebSocket Gateways to deliver real-time messaging. Clients maintain a persistent WebSocket connection alongside their HTTP connection. The backend emits events back to connected clients when new messages arrive, enabling millisecond-latency chat without polling.

​
External services

ServiceProviderUsed for
Google Generative AIGoogleBook summaries, Q&A generation, content analysis
HuggingFaceHuggingFaceSmart recommendations and NLP tasks
Azure Text-to-SpeechMicrosoft AzureAudio narration of book content
Azure Real-time SpeechMicrosoft AzureSpeech-to-text for voice commands
MongoDBSelf-hosted or cloudPrimary data store for users, books, chat, and preferences
All service credentials are injected at runtime via environment variables. See the environment setup guide for the full list of required keys.

​
Docker deployment

The docker-compose.yaml at the repository root defines two services:
  • readrealm-api — The NestJS application built from apps/api/Dockerfile, exposed on port 3000
  • readrealm-mongodb — MongoDB 7.0, exposed on port 27017 with a persistent named volume
Both services communicate over an isolated readrealm-network bridge network. The API container’s MONGODB_URL is automatically set to mongodb://mongodb:27017/readrealm when using Docker Compose. 
task docker:up    # Start API + MongoDB
task docker:down  # Stop all services
task docker:logs  # Stream logs

​
Project structure

readrealm/
├── apps/
│   ├── api/                # NestJS backend — serves all clients
│   │   └── src/
│   │       ├── auth/       # JWT authentication and guards
│   │       ├── book/       # Book management and EPUB processing
│   │       ├── chat/       # Socket.IO real-time chat
│   │       ├── user/       # User profiles and preferences
│   │       ├── verification/  # Email verification workflows
│   │       ├── speech-realtime/  # Voice integration
│   │       ├── guards/     # Auth guards and middleware
│   │       ├── logger/     # Structured logging
│   │       └── main.ts     # Application entry point
│   ├── android/            # Kotlin + Jetpack Compose client
│   ├── ios/                # Swift client
│   └── dashboard/          # Flutter admin dashboard
├── shared/
│   ├── api-spec/
│   │   └── openapi.yaml    # REST API specification
│   └── config/             # Shared environment configuration
├── docker-compose.yaml
└── Taskfile.yml

Build docs developers (and LLMs) love

Get started for freeTalk to us