---

# Project: "Magnit Manager Tycoon & Simulator" (Roblox Luau Full-Stack Game)

## Role & Objective
You are an expert Roblox game developer and software architect specializing in Luau, Roblox Studio APIs, and Rojo project structures. Your task is to design and write the complete, production-ready codebase for a competitive multiplayer Roblox game inspired by the Russian grocery store chain "Magnit" (founded by Sergey Galitsky). 

The game combines active retail simulation (like "Supermarket Simulator") with tycoon progression and competitive multiplayer elements.

---

## Core Game Specifications

### 1. Server & Plot Architecture (6-Player Multiplayer)
- **Max Players per Server:** 6 players.
- **Plot System:** The map contains 6 distinct store plots arranged around a central street/plaza.
- **Claiming & Visiting:** Upon joining, a player is assigned an unclaimed plot. Players can freely walk out of their store and visit the other 5 players' Magnit stores on the server to inspect their layouts, ratings, and prices.
- **Theming:** Red and white color palette (`#E30613` and `#FFFFFF`), stylized after "Магнит у дома" (Magnit Convenience Store), expandable into "Магнит Экстра" (Hypermarket).

### 2. Progression & Core Gameplay Loop
Players start as a basic store clerk in a tiny, rundown store and work their way up to Store Director.
- **Phase 1 (Manual Labor):**
  - Order wholesale boxes of Russian grocery items (milk, bread, dumplings/pelmeni, buckwheat, soda, snacks) via an in-game Manager Tablet UI.
  - Pick up delivery boxes from the curb, carry them inside, and manually stock shelves (`ProximityPrompt` interaction).
  - Operate the cash register: scan items (`ClickDetector` or `ProximityPrompt`), accept cash/card, and give change.
- **Phase 2 (Automation & Staff Management):**
  - Hire NPC Workers via the Tablet UI:
    - **NPC Cashiers:** Automatically process customers in queue.
    - **NPC Stockers:** Pick up boxes from the storage room and refill empty shelves.
    - **NPC Cleaners/Security:** Keep store rating high by cleaning spills and stopping shoplifters.
  - Workers have stats (Speed, Efficiency, Wage) and can be leveled up.
- **Phase 3 (Store Upgrades & Expansion):**
  - Expand floor space, unlock storage rooms, buy better shelving (wooden racks -> metal gondolas -> refrigerated display cases -> bakery section).
  - Exterior upgrades (parking lot, bright neon "МАГНИТ" signage, Galitsky-style park bench decor outside).

### 3. Customer NPC System (AI & Pathfinding)
- **Spawning:** Customers spawn on the main street and choose stores based on Store Rating and Marketing Upgrades.
- **Behavior State Machine:**
  1. `Entering`: Walk into the player's store.
  2. `Shopping`: Use `PathfindingService` to navigate to shelves containing desired items. Take items off shelves (visually removing the 3D item model).
  3. `Queuing`: Line up at an active cash register. Wait patience timer ticks down.
  4. `Checkout`: Pay for items (adds Rubles `₽` to player's balance).
  5. `Leaving`: Exit store and despawn.

### 4. Competitive Systems & Global Leaderboards
- **Data Persistence:** Use `DataStoreService` (with session locking / ProfileService pattern) to save player Rubles (`₽`), Store Level, Inventory, Layout, and Hired Staff.
- **Global Leaderboards (`OrderedDataStore`):**
  - Physical Leaderboard monument in the center of the map displaying the **Top 100 Richest Magnit Managers Globally** (Total Rubles Earned & Store Net Worth).
  - Server-side competition: Live UI widget showing who has the highest revenue per minute on the current 6-player server.

### 5. UI/UX System (Programmatic `ScreenGui`)
Write clean modular UI scripts generating the following interfaces with a modern red/white corporate Magnit aesthetic:
- **HUD:** Rubles (`₽`) counter, Store Rating (1.0 to 5.0 stars), XP bar, "Store Open/Closed" toggle button.
- **Manager Tablet UI:** Tabs for *Wholesale Supply Shop*, *Store Upgrades*, *Staff Hiring*, and *Analytics*.
- **Checkout Minigame UI:** Interactive overlay when the player is manually operating the register.

### 6. Procedural 3D Models & Asset Builder (`ModelGenerator.luau`)
Since we are working in a code environment, create a dedicated server/setup module that procedurally generates clean, color-coded Roblox `Part` / `Model` hierarchies for all required game assets if they don't exist in `ServerStorage`:
- Base Store Plot (walls, automatic sliding doors, red roof banner).
- Shelving units (with attachment points/`Attachment` slots for products).
- Cash register counter with conveyor belt.
- Grocery item models (Milk carton, Bread loaf, Pelmeni pack, Soda bottle) and Cardboard Delivery Boxes.
- Simple R15 NPC rigs with red Magnit employee vests.

---

## Technical Requirements & Architecture
1. **Project Structure:** Organize the project for **Rojo** (`default.project.json`):
   - `src/server/` (PlotManager, DataManager, LeaderboardService, CustomerAIService, WorkerAIService, ShopService)
   - `src/client/` (UIManager, InteractionController, CarryController, CheckoutController)
   - `src/shared/` (Config/Items, Config/Upgrades, Config/Staff, Network/Remotes, AssetBuilder)
2. **Code Quality:**
   - Strictly typed Luau (`--!strict`) where applicable.
   - Server-authoritative economy and inventory (prevent exploits; validate all purchases and checkouts on the server).
   - Network optimization: Manage NPC animations and heavy visuals on the client where possible; use `CollectionService` tags for interactive objects.

---

## Execution Plan (How to Proceed)
Do not write pseudo-code or leave `TODO` placeholders. Build the project step-by-step in our workspace:
1. First, initialize the Rojo directory structure and `default.project.json`.
2. Second, create `src/shared/` configuration files (Items, Upgrades, Remotes) and the procedural `AssetBuilder.luau` so all 3D models, shelves, and the 6 plots are generated via code.
3. Third, implement the Server core (`DataManager`, `PlotManager`, `ShopService`, `LeaderboardService`).
4. Fourth, implement the NPC AI systems (`CustomerAIService` and `WorkerAIService`) alongside manual player mechanics (carrying boxes, stocking shelves, checkout).
5. Finally, build the complete Client UI and interaction controllers.

Start now with Step 1 and Step 2.