System architecture

How the ReadRealm backend, mobile clients, and admin dashboard connect across REST, WebSocket, and external AI services.

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

App	Type	Technology	Purpose	Users
API	Backend	NestJS + TypeScript	Serves all clients, manages data and AI	All clients
Android	Client	Kotlin + Jetpack Compose	Native mobile reading app	End users
iOS	Client	Swift	Native mobile reading app	End users
Dashboard	Admin	Flutter (Web / Desktop / macOS)	Management, analytics, moderation	Administrators

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.

Module	Purpose	Key technologies
auth	User authentication and authorization	JWT, bcrypt
book	Book library management and EPUB parsing	Mongoose, pdf-lib
chat	Real-time conversations	Socket.IO, NestJS Gateways
user	User profile management and preferences	MongoDB, Mongoose
verification	Email verification and OTP workflows	NodeMailer, Crypto
speech-realtime	Voice processing and audio narration	FFmpeg, 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

Service	Provider	Used for
Google Generative AI	Google	Book summaries, Q&A generation, content analysis
HuggingFace	HuggingFace	Smart recommendations and NLP tasks
Azure Text-to-Speech	Microsoft Azure	Audio narration of book content
Azure Real-time Speech	Microsoft Azure	Speech-to-text for voice commands
MongoDB	Self-hosted or cloud	Primary 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