A high-concurrency, scalable marketplace API built with NestJS, Postgres, and Redis.
MarketX is an ambitious open-source marketplace backend engineered for scale, fraud resistance, and lightning-fast developer experience. Designed initially to power peer-to-peer (P2P) commerce, it provides an expansive suite of tightly coupled e-commerce micro-features.
We are currently undertaking a massive open-source contribution wave (via Drips) to fortify the architecture, refactor technical debt, and build out enterprise-grade systems like Escrow and AI Fraud Detection.
- 🛍️ Order & Inventory Engine: Handles concurrent checkout flows, preventing atomic overselling via database locking mechanisms.
- 🏦 Escrow & Payments: Securely holds buyer funds in transit and conditionally releases them to sellers upon confirmed delivery. (Currently being wired to Stripe Connect).
- 🛡️ Fraud Detection: Analyzes heuristics (IP, velocity, value) to algorithmically score and halt suspicious transactions in real-time.
- 🧠 Recommendation Engine: Utilizes browsing history and collaborative filtering to deliver personalized product feeds.
- 🔄 Refunds & Returns: Complex workflows allowing buyers to initiate disputes and request refunds securely.
- 📳 Real-Time Notifications: Internal dispatcher emitting WebSocket, Email, and SMS alerts for critical lifecycle events.
- 🐇 Queue & Event Backbone: Bull-backed workers handle emails, recommendation refreshes, and image processing while RabbitMQ fan-out exchanges broadcast domain events for future microservices.
- Framework: NestJS (Node.js / TypeScript)
- Database: PostgreSQL (via TypeORM)
- Caching & Rate Limiting: Redis
- Testing: Jest (Unit & E2E) & Supertest
Follow these instructions to spin up your local development environment.
Ensure you have the following installed on your machine:
- Node.js (v18+)
- npm or yarn
- Docker & Docker Compose (for spinning up Postgres and Redis easily)
Clone the repository and install the Node dependencies:
git clone https://github.com/Cybermaxi7/MarketX-backend.git
cd MarketX-backend
npm install(Note: As we transition into the open-source phase, we are currently integrating a docker-compose.yml to streamline setup).
For now, assure you have a running PostgreSQL 15 database and a Redis server. Configure your .env file at the root of the project with the necessary credentials:
# Database
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=marketx
# Redis
REDIS_URL=redis://localhost:6379
# RabbitMQ
AMQP_URL=amqp://guest:guest@localhost:5672We provide a minimal Docker Compose profile for local development that starts Postgres, Redis and RabbitMQ. See the full instructions in docs/local-infra.md.
API documentation is generated from NestJS Swagger metadata and published automatically when changes land on main.
npm run docs:generate
npm run docs:renderThis creates:
docs/api/openapi.jsondocs/api/index.html
The API docs workflow is defined in .github/workflows/api-docs.yml and publishes the rendered docs to GitHub Pages.
# Start the development server (with hot-reload)
$ npm run start:dev
# Start in production mode
$ npm run start:prodSecurity scans are now part of the default CI process for main and develop branches, and on pull requests targeting those branches.
- Secret scanning is performed with Gitleaks.
- Dependency vulnerability reporting is performed with
npm audit --audit-level=moderate. - The workflow is defined in
.github/workflows/security.yml.
We require PRs to follow a quality checklist (tests, migration notes, docs). See docs/pr-checklist.md for details and use the repository PR template when opening a PR.
Before opening a PR, run the quick confidence suite:
$ npm run pr:checkThis command runs issue-slice lint checks, issue-slice TypeScript typechecking, and the focused regression test suite used for this contribution wave.
We track major architectural choices in docs/adr/README.md. If a change introduces or materially changes module boundaries, async data flow, infrastructure roles, or long-lived domain workflows, update the relevant ADR or add a new one in the same PR.
We use standardized GitHub issue templates to keep triage fast and consistent. Please choose the template that matches your request:
- Bug report: for defects, regressions, and unexpected behavior. Include reproduction steps, impact, and a validation plan.
- Feature request: for new capabilities or meaningful enhancements. Include the problem, expected value, acceptance criteria, and testing/docs expectations.
- Refactor request: for behavior-preserving structural improvements. Include current pain, goals, non-goals, risks, and regression coverage expectations.
- Tech debt: for shortcuts, brittle patterns, dependency alignment, or missing safeguards that reduce engineering velocity or increase risk over time.
Blank issues are disabled so requests consistently include the details reviewers need to triage, scope, and ship changes safely.
We heavily value test coverage to ensure marketplace stability.
# Run the quick pre-PR confidence suite
$ npm run pr:check
# Run the unit test suite
$ npm run test
# Run the full repository TypeScript typecheck
$ npm run typecheck
# Watch mode for Active Test-Driven Development
$ npm run test:watch
# See code coverage report
$ npm run test:covInterested in collaborating? We'd love your help!
To get started, please browse our active GitHub Issues (or Drips tasks). When you find an issue you'd like to tackle, please read the issue description thoroughly to understand the context, problem, and specific acceptance criteria before beginning your work.
Workflow:
- Fork the repo and identify the issue you want to work on.
- Create your feature branch (
git checkout -b feature/amazing-feature). - Implement the feature or fix, ensuring you meet all acceptance criteria.
- Commit your changes strictly following conventional commit messages.
- Open a Pull Request and link the relevant issue!
MarketX is MIT licensed. If you encounter any issues spinning up the environment, please drop an Issue on GitHub. Let's build something incredible together! 🚀