🌌 Megaverse

A containerized full-stack TypeScript application for managing astral objects in a 2D megaverse map, featuring a React frontend and Express REST API backend with comprehensive testing coverage.

This is a monorepo workspace with the following structure:

• /server - Express REST API server with TypeScript
• /web - React frontend application with TypeScript

Index:

• Getting Started
• Features
• Server architecture
• Technologies Used
• Known misses

Getting started

Prerequisites

• Docker and Docker Compose installed
• Node.js 18+ (for local development)

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Update the environment variables in .env:

• CANDIDATE_ID: Your unique candidate ID
• SERVER_PORT: Port for the API server (default: 4000)
• WEB_PORT: Port for the web frontend (default: 3000)
• SERVER_URL: Base URL for the API server (default: http://localhost)

Running the application

We can build the application through the following command:

npm run build

This will create docker images for both the server and web applications.

To start the application in development mode, we run:

npm run dev

This will:

• Start the API server on http://localhost:4000/api
• Start the web frontend on http://localhost:3000
• Enable hot-reloading for both services

To start the application in production mode:

npm start

For running test cases, we can run:

cd server
npm test              # Run all 127 tests
npm run test:watch    # Watch mode for development
npm run test:coverage # Generate coverage report

Features

• Fetch "current" and "goal" maps
• Fill the "current" map with astral objects based on the "goal" map incrementally, object by object
• Clear the "current" map incrementally
• RESTful API for managing astral objects (Polyanets, Soloons, and Comeths) respecting the Soloon adjacency rules

Map Operations

• GET /api/map/goal - Get the goal map configuration
• GET /api/map/current - Get the current map configuration
• POST /api/map/current - Create objects based on goal map
• DELETE /api/map/current - Clear the current map

Astral Objects

• 🪐 Polyanets: /api/objects/polyanets
• ☀️ Soloons: /api/objects/soloons
• ☄️ Comeths: /api/objects/comeths

Each astral object endpoint supports:

• POST - Create object

And then a general endpoint is offered to delete objects

• DELETE /api/objects - Remove object

Server architecture

The server side application follows several key architectural patterns:

Domain Models

Rich domain objects in server/src/models/ including:

• Position - Coordinate handling and validation
• MegaverseMap - Represents the megaverse map with methods for object management and adjacency validation
• AstralObject - Base class for all astral objects with common properties and methods. Space, Polyanet, Soloon, and Cometh are the specific astral object types with their own symbols and properties

Repository Pattern

All external API calls are abstracted behind repositories in server/src/repositories/:

• RepositoriesManager - Centralized repository management with singleton pattern

The available repositories include:

• MapRepository - Handles map-related operations
• AstralObjectRepository - Manages astral object CRUD operations

Factory Pattern

Domain objects are created through factories in server/src/factories/:

• AstralObjectFactory - Creates astral objects from symbols or structs
• MegaverseMapFactory - Creates map instances from symbols or structs, with proper adjacency validation

Service Layer

Business logic orchestration in server/src/services/:

• Rate limiting for external API calls
• Batch operations with progress reporting
• Strategic ordering (e.g., Soloons placement rules)

Megaverse API Client

This one is used to interact with the external provided API. It handles the retires when 429 code (Too Many Requests) is returned.

Technologies Used

• Docker & Docker Compose for containerization
• TypeScript for type safety across the backend and frontend

Backend

• Node.js with TypeScript for type-safe server development
• Express.js for REST API with custom middleware
• Jest testing framework with 127+ comprehensive tests
• Socket.io for real-time progress updates

Frontend

• React 18 with modern hooks and functional components
• Vite for fast development builds and hot module replacement
• CSS Modules for component-scoped styling
• Socket.io Client for real-time updates

Known misses

• Shared Types: Types are defined in the server package. In a larger system, these would be extracted to a shared library for consistency across frontend and backend.

• State Management: The frontend uses basic React state. For more complex applications, Redux or Zustand would provide better state management.

• Error Handling: The frontend delegates error handling to the backend (acting as a BFF pattern). Production systems would include user-friendly error messaging and retry mechanisms.

• Authentication: The candidateId is environment-based. Production systems would implement proper authentication and authorization layers.

• Performance: While rate limiting is implemented, advanced features like caching, pagination, and optimistic updates are not included in this scope.

• Abort functionality: The current implementation does not support aborting ongoing requests. In production, this would be necessary for user experience and resource management.