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.

Get ReadRealm up and running in minutes. The backend API must be running before the mobile apps and admin dashboard can connect to it.

​
Prerequisites

  • Node.js 20+
  • MongoDB 5+ (local install or Docker)
  • npm or pnpm (comes with Node.js)
If you don’t have MongoDB installed locally, use Docker to start it: docker-compose up -d mongodb

​
30-second setup

1

Clone the repository

git clone https://github.com/aliammari1/readrealm.git
cd readrealm
2

Install all dependencies

Using Task (recommended):
task setup
Or manually:
cd apps/api && npm ci && cd ../..
cd apps/dashboard && flutter pub get && cd ../..
3

Configure environment variables

cp apps/api/.env.example apps/api/.env
Then edit apps/api/.env with your values. The minimum required variables are:
apps/api/.env
MONGO_URL=mongodb://localhost:27017/readrealm
JWT_SECRET=your_jwt_secret_key_min_32_characters_long
GEMINI_API_KEY=your_google_ai_api_key
AZURE_API_TTS_KEY=your_azure_tts_key
AZURE_API_TTS_ENDPOINT=https://your-region.openai.azure.com/
See the Environment Configuration guide for all available variables.
4

Start the backend

task api:dev
Or manually:
cd apps/api && npm run start:dev
The API server starts at http://localhost:3000.
MongoDB must be running before you start the API. If you see a connection error, start MongoDB first or use task docker:up to run MongoDB in Docker.
5

Start the admin dashboard (optional)

In a new terminal:
task dashboard:run
Or manually:
cd apps/dashboard && flutter run -d chrome

​
Run applications

LayerAppCommandPurpose
BackendAPItask api:devCore server at http://localhost:3000
ClientAndroidtask android:buildBuild debug APK
ClientiOSOpen apps/ios/Runner.xcworkspace in XcodeBuild in Xcode
AdminDashboardtask dashboard:runAdmin dashboard (web/desktop)

​
Task command reference

task api:dev          # Start development server (hot reload)
task api:build        # Build for production
task api:test         # Run unit tests
task api:test:e2e     # Run end-to-end tests

​
Troubleshooting

Install the Task CLI:
# macOS
brew install go-task/tap/go-task

# Linux
sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b ~/.local/bin

# Windows (via Scoop)
scoop install task
Alternatively, run commands manually without Task:
cd apps/api && npm run start:dev
cd apps/dashboard && flutter run -d chrome
If the API fails to start with a MongoDB connection error:
# Check if MongoDB is running locally
mongosh localhost:27017

# Or start MongoDB via Docker
docker-compose up -d mongodb

# Check MongoDB logs
docker-compose logs -f mongodb
Make sure MONGO_URL in your apps/api/.env matches where MongoDB is running.
# Find what's using port 3000
lsof -i :3000

# Kill the process
kill -9 <PID>

# Or start the API on a different port
PORT=3001 npm run start:dev

# Check Flutter installation
flutter doctor

# Clean and reinstall dependencies
flutter clean
flutter pub get

# Run again
flutter run -d chrome

​
Next steps

Environment Configuration

Configure all API keys and service integrations.

Docker Deployment

Run the full stack with Docker Compose.

Architecture

Understand how all the components connect.

API Reference

Explore the REST API and WebSocket interface.

Build docs developers (and LLMs) love

Get started for freeTalk to us