MixMatch

Welcome to the MixMatch codebase! This is a monorepo managing the frontend, backend API, and Stellar/Web3 services for the MixMatch platform.

We use pnpm workspaces for dependency management and TurboRepo for high-performance build orchestration.

🚀 Tech Stack

• Monorepo Manager: pnpm workspaces + TurboRepo
• Frontend: Next.js 14+ (App Router), TailwindCSS
• Backend: Node.js, Express, TypeScript
• Web3: Stellar SDK (Soroban)
• Language: TypeScript (Strict Mode)

---

🛠 Prerequisites

Before you start, ensure you have the following installed:

1. Node.js (v18 or higher recommended)
2. pnpm (We use this instead of npm/yarn)

corepack enable
# OR
npm install -g pnpm

---

⚡️ Getting Started

Follow these steps to get the entire platform running locally.

1. Clone & Install

git clone <your-repo-url>
cd MixMatch-Onchain

# Install all dependencies for all apps and packages
pnpm install

2. Run Development Server

This command starts all applications (Web, API, and Stellar Service) in parallel.

pnpm dev

You will see output from all services in your terminal. They are available at:

• Web App: http://localhost:3000
• Backend API: http://localhost:3001
• Stellar Service: http://localhost:3002

---

📂 Project Structure

mixmatch/
├── apps/
│   ├── web/               # Next.js Frontend (User & Admin Interface)
│   ├── api/               # Core Backend API (Express + Node.js)
│   └── stellar-service/   # Isolated Service for Blockchain/Payments
│
├── packages/
│   ├── types/             # Shared TypeScript interfaces & DTOs
│   ├── config/            # Shared configurations (TSConfig, ESLint)
│   └── ui/                # Shared React UI components (Tailwind)
│
└── turbo.json             # Build pipeline configuration

---

📜 Available Scripts

Run these from the root folder:

Command	Description
pnpm dev	Starts all apps in development mode.
pnpm build	Builds all apps and packages for production.
pnpm lint	Runs ESLint across the entire monorepo.
pnpm test	Runs tests for all packages (when added).
pnpm clean	(Optional) Clears Turbo cache and artifacts.

---

🧩 Adding Dependencies

Since we use a monorepo, you must specify where to install a package.

To add a library to the Frontend (apps/web):

# Example: Adding Framer Motion to the web app
cd apps/web
pnpm add framer-motion

To add a library to the Backend (apps/api):

cd apps/api
pnpm add mongoose

To use a shared package (e.g., using Types in API): Note: This is already set up, but for reference:

cd apps/api
pnpm add "@mixmatch/types@workspace:*" -D

---

⚠️ Troubleshooting

"Module not found" or Type Errors If you just pulled fresh code or switched branches:

pnpm install
# If issues persist, force a clean install
rm -rf node_modules
pnpm install

Git is ignoring files I want to commit We strictly ignore node_modules and build artifacts (.next, dist).

• Do not force commit node_modules.
• If your node_modules are showing up in Git, run:

git rm -r --cached .
git add .
git commit -m "fix: clear cached node_modules"

---

🤝 Contribution Guidelines

1. Always run pnpm lint before pushing.
2. Keep shared logic (types, configs) in packages/.
3. Do not edit apps/*/node_modules manually.

---

🔒 Branch Protection (Repository Admin)

To enforce CI checks and prevent breaking changes from being merged:

1. Navigate to Settings → Branches → Add branch protection rule
2. Set branch name pattern: main
3. Enable the following rules:
   • ✅ Require status checks to pass before merging
   • ✅ Require branches to be up to date before merging
   • ✅ Select required status check: Lint, Typecheck, and Build / ci
   • ✅ Restrict who can push to matching branches (prevents direct pushes to main)

This ensures all pull requests pass linting, type checking, and build validation before merging.