A NestJS-based REST API for managing genetic algorithms and breeding mechanics for Beebea robots - digital collectible characters with elemental types and unique genetic traits.
Beebea Robots API provides a complete backend solution for managing digital collectible robots with:
- Genetic Generation: Random genome creation with elemental attributes (Fire, Water, Earth, Wind)
- Breeding Mechanics: Multi-point crossover algorithms with mutation
- Siring System: Track breeding history and parentage
- AWS S3 Integration: Secure storage for genetic data
- User Profiles: Manage user collections and robot ownership
- Framework: NestJS 11.x
- Language: TypeScript 5.4
- Database: PostgreSQL with TypeORM 0.3.x
- Logging: Pino with nestjs-pino
- Validation: class-validator & class-transformer
- Configuration: @nestjs/config with Joi validation
- AWS SDK: @aws-sdk/client-s3
- Hashing: sha3 (Keccak-256)
- Testing: Jest 30.x
The core genetics engine for the Beebea ecosystem:
- Genome Generation: Creates random genomes with elemental types and trait variations
- Breeding Algorithm: Multi-point crossover between parent genomes with configurable mutation rate (1%)
- Fitness Evaluation: Element-specific weighting for genome quality assessment
- Siring History: Tracks all breeding operations and lineage
- S3 Storage: Persists genetic JSON data to AWS S3
Element Types:
| Element | ID | Hue Range | Color |
|---|---|---|---|
| Fire | 0 | 0-55 | Red-orange |
| Water | 1 | 170-215 | Cyan-blue |
| Earth | 2 | 35-130 | Yellow-green |
| Wind | 3 | 186-325 | Blue-purple |
Genome Structure:
- Head Traits: eyes, nose, ears, mouth, shape (each with shape 1-5 and HSL color)
- Body Traits: skin, backpack, shape (each with shape 1-5 and HSL color)
- Hands/Feet Traits: skin, hands, feet (each with shape 1-5 and HSL color)
| Method | Endpoint | Description |
|---|---|---|
| GET | /genetics/:elementHash |
Retrieve genome by hash |
| GET | /genetics/add/:populationCount |
Initialize population with N genomes |
- Selection: Two parent genomes are selected for breeding
- Crossover: Multi-point crossover combines parent traits
- Mutation: 1% chance of random mutation in shape or color
- Fitness: Offspring evaluated based on element-specific weights
- Storage: New genome saved to S3, metadata to PostgreSQL
- History: Siring record created linking parents to offspring
TypeORM configuration with PostgreSQL:
- Async configuration via ConfigService
- Snake case naming strategy for database columns
- Auto-load entities from project
- Soft delete support via @DeleteDateColumn
- All entities extend BaseEntity (id, createdAt, updatedAt, deletedAt)
AWS S3 integration for:
- Storing genetic data as JSON files
- Generating presigned URLs for secure access
- Organized bucket structure for genome retrieval
User profile management:
- User account management
- Many-to-many relationship between users and their BeeBea collections
- Profile-BeeBea linking entity for ownership tracking
# Install dependencies
$ pnpm install
# Copy and configure environment variables
$ cp .env .env.local
# Edit .env.local with your database and AWS credentials# Database
DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_USERNAME=postgres
DATABASE_PASSWORD=postgres
DATABASE_NAME=beebea_robots
# Application
PORT=3000
HOST=localhost
LOG_LEVEL=debug
# AWS S3
AWS_BEEBEA_USER_ACCESS_KEY=your_access_key
AWS_BEEBEA_USER_SECRET_KEY=your_secret_key
AWS_BEEBEA_BUCKET_NAME=your_bucket_name
AWS_BEEBEA_BUCKET_REGION=your_bucket_region# Development with watch mode
$ pnpm start:dev
# Production build
$ pnpm build
$ pnpm start:prod
# Debug mode
$ pnpm start:debug# Start PostgreSQL and pgAdmin
$ docker-compose up -d
# Services:
# - PostgreSQL on port 5432
# - pgAdmin on port 5050Base URL: http://localhost:3000
# Unit tests
$ pnpm test
# Watch mode
$ pnpm test:watch
# Coverage report
$ pnpm test:cov
# End-to-end tests
$ pnpm test:e2e# Linting
$ pnpm lint
# Format code
$ pnpm format