AI Premier League (AIPL)

A cricket franchise management simulator built on the MERN stack (MongoDB, Express, React, Node.js), based on the AIPL Product Requirements Document.

This is a multi-phase build. See PROGRESS.md for exactly what's implemented so far and what's still coming in the next work cycle.

Quick start

Prerequisites

• Node.js 18+
• MongoDB running locally on mongodb://127.0.0.1:27017, or a MongoDB Atlas connection string

npm install
npm run dev

That's it. npm install (run once, from the repo root) installs both the backend and frontend via npm workspaces. npm run dev boots:

• the Express API on http://localhost:5000
• the React app on http://localhost:5173

The frontend's dev server proxies /api/* to the backend automatically, and the backend auto-seeds the default franchises and player database into MongoDB the first time it connects to an empty database — no manual seed step required.

If you don't have MongoDB installed

Install MongoDB Community Server and make sure mongod is running, or create a free MongoDB Atlas cluster and put its connection string in backend/.env as MONGO_URI. Without a reachable database the API will start but most endpoints will return connection errors — the frontend itself will still load.

Re-seeding the database

npm run seed

This wipes and reloads the franchises, stadiums, legends and real-player roster. (Not required for normal use - it's just there if you want to reset to a clean state.)

Importing/updating the real player roster

The full current-player database (~480 players, growing toward 600-700) lives at backend/seed/data/players_source.json. It's synced into MongoDB automatically every time the server boots - no manual step needed. If you replace that file with a bigger one later, just restart the server (or run the line below) and it picks up the new players without touching anyone already signed to a squad, in training, etc:

npm run import:players

Troubleshooting: "my players aren't showing up in MongoDB"

Check these in order:

1. Is MongoDB actually running? mongod needs to be running locally (or MONGO_URI in backend/.env needs to point at a reachable Atlas cluster). The backend logs [DB] MongoDB connected -> ... on success - if you don't see that line in the terminal running npm run dev, the import never had anywhere to write to.
2. Are you looking at the right database name? The app connects to a database named aipl by default (see MONGO_URI in backend/.env). In MongoDB Compass or mongosh, make sure you've selected the aipl database, not test or admin, and the players collection inside it.
3. Did the import actually run? Look for [SEED]/[IMPORT] lines in the backend terminal output on startup. If MongoDB wasn't reachable at boot, seeding is skipped silently rather than retried - restart the backend once MongoDB is confirmed running.
4. Importing the raw JSON file directly into MongoDB (e.g. via mongoimport or Compass's "Import Data")? Don't - the raw file's field names (team, batting, rating, etc.) don't match this app's schema, so the API will look like it's returning broken/empty player data even though documents exist. Always go through npm run import:players (or just restart the server), which transforms the file into the shape the app expects.

Project structure

AIPL/
├── backend/            Express + Mongoose API
│   ├── config/         DB connection
│   ├── models/         Mongoose schemas (10 collections from the PRD)
│   ├── controllers/    Route handlers
│   ├── routes/         Express routers
│   ├── middleware/     Auth (JWT) + error handling
│   └── seed/           Default franchises + player database
└── frontend/           React + Vite + Tailwind + Redux Toolkit + Framer Motion
    └── src/
        ├── components/ Layout, shared UI, team-specific components
        ├── pages/       Route-level screens
        ├── store/       Redux Toolkit slices (auth, dynamic team theme)
        └── api/         Axios calls to the backend

In-app Assistant

Every page has a small "?" button bottom-right - an Owner's Office assistant. The Quick Help tab always works with zero setup (static tips per page). The Ask AI tab uses your own Anthropic API key to answer free-form questions about how the league works, grounded in what's actually built (it's told not to describe unbuilt features as if they exist). To enable it:

1. Get a key at https://console.anthropic.com
2. Add it to backend/.env: ANTHROPIC_API_KEY=sk-ant-...
3. Restart the backend

Without a key, "Ask AI" just explains that and points back to Quick Help - nothing breaks.

Tech stack (per the PRD)

• Frontend: React.js, Tailwind CSS, Framer Motion, React Router
• Backend: Node.js, Express.js
• Database: MongoDB (via Mongoose)
• State management: Redux Toolkit

Notes on real player names

The player database uses real cricketers' names and publicly known career information for gameplay flavor, as the PRD's "Real Player Database" section requests. Attribute ratings (technique, power, yorker, etc.) are simulation values created for game balance, not official statistics. Franchise names, logos, and city pairings are original/fictional so the project doesn't depend on any league's trademarked branding.