Development Workflow

Day-to-day development tasks for ReadRealm — running services, using the Taskfile, and following code style guidelines for each platform.

ReadRealm is a multi-tier monorepo with four applications. This page covers how to run each app during development, the full Taskfile command reference, and code style guidelines per platform.

Architecture overview

The four apps and their roles:

App	Technology	Location	Purpose
Backend (API)	NestJS, TypeScript, MongoDB	apps/api/	Serves all clients via REST and WebSocket
Android client	Kotlin, Jetpack Compose, Gradle	apps/android/	Native reader app for Android
iOS client	Swift, Xcode	apps/ios/	Native reader app for iOS
Admin dashboard	Flutter, Dart	apps/dashboard/	Web/desktop management interface

All client apps connect to the backend at http://localhost:3000.

Quick start

The fastest way to get all services running:

# Step 1: Install all dependencies (first-time only)
task setup

# Step 2: Start the backend API
task api:dev

# Step 3: In a separate terminal, start the admin dashboard
task dashboard:run

# Step 4: Run the full test suite
task test

The Android and iOS client apps connect to the same backend. Start task api:dev before running the mobile apps.

Taskfile command reference

Setup

Task	Description
task setup	First-time setup — installs all dependencies

Backend (API)

Development

# Install backend dependencies
task api:install

# Start development server with watch mode (http://localhost:3000)
task api:dev

# Build for production
task api:build

Tests

# Run unit tests
task api:test

# Run end-to-end tests
task api:test:e2e

Quality

# Lint TypeScript code
task api:lint

# Format TypeScript code with Prettier
task api:format

Android client

Build

# Sync Gradle dependencies
task android:install

# Build debug APK
task android:build

# Build release APK
task android:build:release

# Install debug APK to connected device or emulator
task android:install:device

Tests

# Run unit tests
task android:test

iOS client

Build

# Open Xcode workspace
task ios:build
# Then run: open apps/ios/Runner.xcworkspace

Tests

# Run unit tests via xcodebuild
task ios:test

Admin dashboard (Flutter)

Development

# Install Flutter dependencies
task dashboard:install

# Run on Chrome (web)
task dashboard:run

# Run on Windows desktop
task dashboard:run:windows

# Run on macOS desktop
task dashboard:run:macos

Build

# Build web version
task dashboard:build:web

# Build Windows executable
task dashboard:build:windows

Tests

# Run Flutter tests
task dashboard:test

Docker

# Start API and MongoDB services
task docker:up

# Stop all services
task docker:down

# View live service logs
task docker:logs

Code quality (all platforms)

# Run all tests (API + dashboard)
task test

# Run E2E tests
task test:e2e

# Lint all code
task lint

# Format all code
task format

Code style guidelines

Backend — NestJS / TypeScript

• Follow the NestJS module structure: controllers, services, and modules.
• Place new features in their own module directory under apps/api/src/.
• Use class-validator and class-transformer for DTO validation.
• Use JWT for authentication via the existing auth module.
• Document all API endpoints in the OpenAPI spec.
• Add database migrations for any schema changes.
• Aim for greater than 80% test coverage on new code.

Linting and formatting:

# Lint (ESLint + TypeScript rules, auto-fixes)
npm run lint

# Format (Prettier)
npm run format

Tooling: ESLint with @typescript-eslint, Prettier via eslint-plugin-prettier.

Android — Kotlin / Jetpack Compose

• Use Jetpack Compose for all UI.
• Follow Material Design 3 guidelines.
• Handle API errors gracefully with user-facing feedback.
• Implement offline-first caching where appropriate.
• Test on multiple Android versions (API level 24 and above).

Build and test:

./gradlew assembleDebug
./gradlew test

iOS — Swift / SwiftUI

• Use SwiftUI for all new UI.
• Follow Apple Human Interface Guidelines.
• Implement proper error handling and propagation.
• Support iOS 13 and above.
• Test on different device sizes and orientations.

Build and test:

open apps/ios/Runner.xcworkspace
xcodebuild test -workspace Runner.xcworkspace -scheme Runner

Admin dashboard — Flutter / Dart

• Use Provider for state management.
• Follow Material Design 3 guidelines.
• Make the UI responsive across desktop, tablet, and web viewports.
• Write widget tests for new components.
• Use meaningful, descriptive variable names.

Install and run:

flutter pub get
flutter run -d chrome

API source structure

The NestJS backend in apps/api/src/ is organized by feature module:

apps/api/src/
├── app.module.ts          # Root application module
├── main.ts                # Application entry point
├── auth/                  # JWT authentication
├── book/                  # Book management, EPUB, reviews, TTS
├── chat/                  # Real-time chat (Socket.IO)
├── user/                  # User management
├── verification/          # Account verification
├── services/              # Shared services
├── guards/                # Auth guards
├── config/                # Configuration
└── logger/                # Logging

When adding a new feature, create a corresponding module directory following the existing pattern.

Run task info to print a summary of the project structure and available commands at any time.