A decentralized & OpenSource language learning platform built with Node.js, Express, TypeScript, React, and React Native. WayrApp mission is to provide a complete ecosystem including a robust backend API, web-based content creator tool, and mobile application for language learning.
This repository is organized as an NPM Workspaces monorepo containing:
frontend-creator/) - React web application for creating educational contentfrontend-mobile/) - Cross Platform React Native mobile applicationfrontend-shared/) - Frontend shared utilities and components-Ready to Deploy Backend - Node.js/Express API server with PostgreSQL database and Prisma ORM (TODO: Expand to make it DB-Agnostic)
wayrapp/
├── src/ # Backend API source code
│ ├── __tests__/ # Integration tests
│ │ └── integration/ # Cross-module integration tests
│ ├── modules/ # Feature modules (domain-driven design)
│ │ ├── users/ # User management & authentication
│ │ │ ├── controllers/ # HTTP request handlers
│ │ │ ├── services/ # Business logic
│ │ │ ├── repositories/ # Data access layer
│ │ │ ├── routes/ # Route definitions
│ │ │ ├── types/ # Module-specific types
│ │ │ └── __tests__/ # Module unit tests
│ │ ├── content/ # Course content management
│ │ │ ├── controllers/ # Content CRUD operations
│ │ │ ├── services/ # Content business logic
│ │ │ ├── repositories/ # Content data access
│ │ │ ├── routes/ # Content API routes
│ │ │ ├── schemas/ # Content validation schemas
│ │ │ ├── types/ # Content type definitions
│ │ │ └── __tests__/ # Content module tests
│ │ └── progress/ # Progress tracking & gamification
│ │ ├── controllers/ # Progress API handlers
│ │ ├── services/ # Progress calculations
│ │ ├── repositories/ # Progress data persistence
│ │ ├── routes/ # Progress API routes
│ │ ├── types/ # Progress type definitions
│ │ └── __tests__/ # Progress module tests
│ ├── shared/ # Shared utilities and infrastructure
│ │ ├── database/ # Database connection & utilities
│ │ ├── middleware/ # Express middleware (auth, validation, etc.)
│ │ ├── schemas/ # Zod validation schemas
│ │ ├── utils/ # Utility functions & helpers
│ │ ├── types/ # Shared TypeScript types
│ │ ├── routes/ # Shared routes (health checks)
│ │ └── test/ # Test utilities & setup
│ │ ├── factories/ # Test data factories
│ │ ├── fixtures/ # Test fixtures
│ │ ├── utils/ # Test helper functions
│ │ ├── setup.ts # Global test configuration
│ │ └── testDb.ts # Test database utilities
│ ├── types/ # Global type definitions
│ ├── app.ts # Express app configuration
│ ├── server.ts # Server entry point
│ └── testInfo.ts # Testing documentation & metadata
├── frontend-creator/ # Content Creator Web App (React + Vite)
│ ├── src/ # React application source
│ ├── dist/ # Built web application
│ ├── public/ # Static assets
│ ├── scripts/ # Build scripts
│ ├── package.json # Creator-specific dependencies
│ ├── vite.config.ts # Vite configuration
│ └── tailwind.config.js # Tailwind CSS configuration
├── frontend-mobile/ # Mobile Application (React Native + Expo)
│ ├── src/ # React Native source
│ ├── assets/ # Mobile app assets
│ ├── dist/ # Built mobile application
│ ├── app.json # Expo configuration
│ └── package.json # Mobile-specific dependencies
├── frontend-shared/ # Shared Frontend Code
│ ├── types/ # Shared TypeScript types
│ ├── utils/ # Shared utility functions
│ ├── dist/ # Built shared components
│ ├── __mocks__/ # Jest mocks for shared code
│ └── package.json # Shared dependencies
├── prisma/ # Database schema & migrations
│ ├── migrations/ # Database migration files
│ └── schema.prisma # Prisma database schema
├── scripts/ # Build & deployment scripts
│ ├── setup-test-db.js # Test database setup script
│ └── check-test-config.js # Test configuration validator
├── docs/ # Generated backend & ecosystem documentation
├── logs/ # Application logs
├── .env.example # Environment template
├── .env.test.example # Test environment template
├── jest.config.js # Unit tests configuration
├── jest.integration.config.js # Integration tests configuration
├── tsconfig.json # TypeScript configuration
├── typedoc.json # Documentation generation config
└── package.json # Root monorepo configuration
The core API server providing authentication, content management, and progress tracking services.
Key Features:
Access: http://localhost:3000 (development)
frontend-creator/)Web-based application for educators and content creators to build language learning courses.
Key Features:
Access: http://localhost:5173 (development)
frontend-mobile/)Cross-platform mobile application for learners to access courses and track progress.
Key Features:
Access: Expo development server (see mobile app documentation)
frontend-shared/)Common utilities, types, and components shared between frontend applications.
Includes:
Design System:
Two complementary documentation systems:
GET /swagger - Interactive Swagger UI - Test API endpoints directly in your browser (styled with WayrApp design tokens)GET /api-docs - Alternative Swagger UI interfaceGET /api/swagger.json - OpenAPI 3.0 specification (JSON) - Serverless-optimized with fallbackGET /api/docs/overview - Comprehensive API overviewGET /api/status - API status and health checkWhen running the server locally, you can access comprehensive backend API documentation:
| Endpoint | Description |
|---|---|
/api/docs |
OpenAPI 3.0 specification (Swagger compatible) |
/api/docs/overview |
API overview with usage patterns |
/api/docs/authentication |
Authentication endpoints and security |
/api/docs/users |
User management operations |
/api/docs/content |
Content hierarchy management |
/api/docs/lessons-exercises |
Lesson and exercise management |
/api/docs/progress |
Progress tracking and gamification |
/api/docs/packaged-content |
Offline support implementation |
/api/docs/database-setup |
Database setup instructions |
# Interactive API Documentation (open in browser)
open http://localhost:3000/swagger
# Get OpenAPI specification
curl http://localhost:3000/api/swagger.json
# Get API information
curl http://localhost:3000/api
# Check API status
curl http://localhost:3000/api/status
# Health check
curl http://localhost:3000/health
# Test authentication endpoint
curl -X POST http://localhost:3000/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"email":"user@example.com","password":"password123"}'
Clone the repository
git clone https://github.com/exetrujillo/wayrapp.git
cd wayrapp
Install all dependencies (installs for all workspaces)
npm install
Set up environment variables
cp .env.example .env
# Edit .env with your database URL and other configurations
Set up the database
npm run db:generate
npm run db:migrate
Set up test environment (for running tests safely)
cp .env.example .env.test
# Edit .env.test with a SEPARATE test database URL
npm run test:db:setup
Start all applications in development mode
npm run dev:all
Or start individual applications:
# Backend API only
npm run dev
# Content Creator only
npm run dev --workspace=frontend-creator
# Mobile app only
npm run dev --workspace=frontend-mobile
npm run build:all - Build all applicationsnpm run dev:all - Start all applications in development modenpm run test:all - Run tests for all applicationsnpm run lint:all - Lint all applicationsnpm run format:all - Format code for all applicationsnpm run dev - Start backend development server with hot reloadnpm run build - Build backend for productionnpm run start - Start backend production servernpm run test - Run backend unit testsnpm run test:integration - Run integration tests (requires test DB setup)npm run test:integration:safe - Setup test DB and run integration tests safelynpm run test:backend - Run all backend tests (unit + integration)npm run test:watch - Run backend tests in watch modenpm run test:db:setup - Setup test database schemanpm run test:db:check - Verify test/production database separationnpm run db:generate - Generate Prisma clientnpm run db:migrate - Run database migrationsnpm run db:studio - Open Prisma Studionpm run db:test - Test database connectionnpm run dev --workspace=frontend-creator - Start content creator in developmentnpm run build --workspace=frontend-creator - Build content creator for productionnpm run dev --workspace=frontend-mobile - Start mobile app in developmentnpm run build --workspace=frontend-mobile - Build mobile app for productionCreate a .env file based on .env.example:
# Database
DATABASE_URL="postgresql://username:password@...?sslmode=require"
# JWT Configuration
JWT_SECRET="your-super-secure-jwt-secret-key-here"
JWT_REFRESH_SECRET="your-super-secure-refresh-secret-key-here"
# Server Configuration
PORT=3000
NODE_ENV="development"
CRITICAL: Create a separate .env.test file for testing to prevent data loss:
# Test Environment Configuration
NODE_ENV="test"
# Test Database Configuration - MUST BE SEPARATE FROM PRODUCTION
DATABASE_URL="postgresql://username:password@...test_database?sslmode=require"
# JWT Configuration (same as dev for testing)
JWT_SECRET="your-super-secure-jwt-secret-key-here"
JWT_REFRESH_SECRET="your-super-secure-refresh-secret-key-here"
# Server Configuration
PORT=3001
# Logging (minimal for tests)
LOG_LEVEL="error"
# Security (faster for tests)
BCRYPT_ROUNDS=4
⚠️ WARNING: Never use the same database for testing and production. Tests will delete all data during cleanup.
The vercel.json file is configured to handle both API and documentation routing:
{
"rewrites": [
{ "source": "/swagger", "destination": "/swagger.html" },
{ "source": "/docs", "destination": "/docs-redirect.html" },
{ "source": "/api/(.*)", "destination": "/api" }
]
}
Important: Uses rewrites instead of routes to avoid Vercel configuration conflicts.
The project uses TypeScript with different configurations for different environments:
tsconfig.json - Base TypeScript configurationtsconfig.build.json - Production build configuration (extends base config)# Build for production
npm run build
The application uses a hierarchical content structure:
Course
├── Level (A1, A2, B1, etc.)
│ └── Section (Topics within a level)
│ └── Module (Learning units)
│ └── Lesson (Individual lessons)
│ └── Exercise (Practice activities)
The monorepo includes comprehensive test coverage across all applications with separate test databases to ensure production data safety.
IMPORTANT: Tests use a separate test database to prevent data loss.
ARCHITECTURAL DECISION: All tests (unit and integration) require a test database configuration. This is intentional to enforce security and prevent accidental data loss.
Before running any tests:
cp .env.example .env.test
# Edit .env.test with your TEST database URL
npm run test:db:check # Ensures test/production databases are separate
npm run test:db:setup # Initializes test database schema
# Run tests for all applications
npm run test:all
# Backend tests
npm test # Unit tests only
npm run test:integration:safe # Integration tests (with DB setup)
npm run test:backend # All backend tests (unit + integration)
# Run tests for specific workspace
npm run test --workspace=frontend-creator
npm run test --workspace=frontend-mobile
npm run test --workspace=frontend-shared
# Run tests in watch mode
npm run test:watch # Backend unit tests only
npm run test --workspace=frontend-creator -- --watch # Creator only
# Run tests with coverage
npm run test:coverage # Backend only
.test.ts): Fast, isolated tests that don't require database.integration.test.ts): Full API tests using separate test database.test.tsx): Frontend component testsThe testing system includes multiple safety measures:
Test files are located alongside source files with .test.ts or .test.tsx extensions.
# Build all applications
npm run build:all
# Start backend in production
npm start
The monorepo is configured for deployment on Vercel with the following setup:
# Deploy to Vercel
npm run deploy:vercel
The vercel.json configuration handles:
/api/*) → Backend serverless functions (api/index.js)/swagger → Interactive Swagger UI (swagger.html)/docs → Documentation disambiguation page (docs-redirect.html)/ → Main landing page (index.html).vercelignore for faster deploymentsKey files for Vercel deployment:
tsconfig.build.json - Production TypeScript configurationapi/index.js - Serverless function handler.vercelignore - Excludes unnecessary files from deployment# Multi-stage Dockerfile for monorepo
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
COPY frontend-*/package.json ./frontend-*/
RUN npm ci
COPY . .
RUN npm run build:all
FROM node:18-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/frontend-creator/dist ./frontend-creator/dist
COPY --from=builder /app/frontend-mobile/web-build ./frontend-mobile/web-build
COPY --from=builder /app/package*.json ./
COPY --from=builder /app/prisma ./prisma
RUN npm ci --only=production && npx prisma generate
EXPOSE 3000
CMD ["npm", "start"]
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)The API follows RESTful conventions with consistent response formats:
Success Response:
{
"success": true,
"timestamp": "2023-07-20T12:34:56.789Z",
"data": {
// Response data here
}
}
Error Response:
{
"success": false,
"timestamp": "2023-07-20T12:34:56.789Z",
"error": {
"code": "ERROR_CODE",
"message": "Human readable error message",
"details": "Additional error details (optional)",
"path": "/api/endpoint"
}
}
Most endpoints require JWT authentication:
Authorization: Bearer <your-jwt-token>
API endpoints are rate-limited to prevent abuse:
/health endpoint for monitoringDatabase Connection Issues
Test Database Issues
.env.test exists with separate test database URLnpm run test:db:check to verify database separationnpm run test:db:setup to initialize test databaseMigration Failures
Test Failures
Authentication Issues
This project is licensed under the MIT License - see the LICENSE file for details.