# The Crime Syndicate - Code Analysis & Improvement Plan

**Generated:** 2026-07-04  
**Project:** Laravel-based Omerta/Torn City-style browser game  
**Current Status:** Phase 1 mostly complete, Phase 2 partially started

---

## 📊 Current Implementation Overview

### ✅ What's Already Implemented

#### Core Systems
- [x] **User Authentication** - Laravel Breeze setup with registration, login, password reset
- [x] **Character System** - Full character model with stats (strength, defense, speed, dexterity)
- [x] **Energy System** - Regeneration, costs, service layer
- [x] **Health System** - Damage, healing, hospital mechanics
- [x] **Nerve System** - Separate resource for crimes, midnight refill
- [x] **Money & Bank** - Cash, bank deposits/withdrawals, daily interest
- [x] **Experience & Leveling** - EXP curve, level up rewards, stat increases

#### Gameplay Features
- [x] **Crime System** - Crimes with difficulties, success rates, rewards, cooldowns
- [x] **Inventory System** - Items, equipment, consumables with equip/use functionality
- [x] **Gym/Training** - Stat training with daily caps
- [x] **Jail System** - Sentencing, bust-out mechanic (recently added)
- [x] **Hospital System** - Death, revival with costs
- [x] **Location System** - Basic location model
- [x] **Notifications** - System notifications for game events
- [x] **Activity Logging** - Comprehensive action tracking

#### Infrastructure
- [x] **Service Layer** - CrimeService, EconomyService, EnergyService, HealthService, NerveService, JailService, TrainingService, NotificationService
- [x] **Middleware** - VerifyCharacter, CheckEnergy, CheckInHospital, CheckInJail
- [x] **Configuration** - Comprehensive game.php config with all mechanics
- [x] **Enums** - CharacterStatus, CrimeDifficulty, ItemType, AttackResult
- [x] **Scheduled Commands** - Energy regen, health regen, nerve midnight refill
- [x] **Database** - 14+ migrations covering all core tables
- [x] **Routes** - Well-structured web.php and game.php routing

#### Frontend
- [x] **Blade Templates** - Game views for crimes, character, dashboard, jail, hospital
- [x] **Tailwind CSS** - Styling framework
- [x] **Alpine.js** - Frontend interactivity

---

## 🎯 Strengths of Current Implementation

### 1. **Excellent Architecture**
- Clean separation of concerns with dedicated service classes
- Proper use of Laravel features (middlewares, enums, policies)
- Well-organized configuration in game.php
- Good use of model methods and accessors

### 2. **Solid Core Mechanics**
- Energy/Nerve/Health systems are well-implemented
- Crime system with configurable difficulties and rewards
- Character progression with EXP and leveling
- Comprehensive economy with bank interest

### 3. **Good Code Quality**
- Type hints where appropriate
- Clear method naming and responsibilities
- Proper error handling
- Good use of Laravel's ORM relationships

### 4. **Extensible Design**
- Configuration-driven mechanics
- Service-based architecture makes adding features easy
- Middleware system allows for flexible access control
- Event logging is comprehensive

---

## ⚠️ Code Improvements Needed

### 🔴 High Priority Issues

#### 1. **Service Injection Improvements**
**Problem:** Services are manually instantiated with `new` instead of using dependency injection.

```php
// Current (in CrimeService.php line 20-22)
public function __construct()
{
    $this->energyService = new EnergyService();
    $this->economyService = new EconomyService();
    $this->nerveService = new NerveService();
}
```

**Solution:** Use Laravel's dependency injection container:
```php
public function __construct(
    EnergyService $energyService,
    EconomyService $economyService,
    NerveService $nerveService
) {
    $this->energyService = $energyService;
    $this->economyService = $economyService;
    $this->nerveService = $nerveService;
}
```

**Files to update:**
- `app/Services/Game/CrimeService.php`
- `app/Services/Game/EconomyService.php` (remove circular dependency)
- `app/Http/Controllers/Game/CrimeController.php`
- `app/Http/Controllers/Game/CharacterController.php`
- All other controllers and services

#### 2. **Circular Dependency Issue**
**Problem:** `EconomyService` depends on `ActivityLog` model, which may cause issues. Also, `Character` model methods are used directly by services.

**Solution:** 
- Move ActivityLog methods to a dedicated `ActivityLogService`
- Use interfaces for service dependencies
- Extract character stat modifications to a `CharacterStatService`

#### 3. **Missing Attack/PvP System**
**Problem:** Character model has `getAttackPowerAttribute()` and `getDefenseAttribute()` but no actual PvP combat implementation.

**Files needed:**
- `app/Models/Attack.php` (migration and model)
- `app/Services/Game/CombatService.php`
- `app/Http/Controllers/Game/AttackController.php`
- `app/Http/Middleware/Game/CheckAlive.php`
- `app/Http/Middleware/Game/CheckCooldown.php`

#### 4. **Hardcoded Character Status Checks**
**Problem:** Status checking logic is duplicated across models and services.

**Example:** `Character::canAct()` checks status, but middleware and services repeat this logic.

**Solution:** Centralize status checking in a `CharacterStatusService` or use the existing enum methods consistently.

#### 5. **Missing Cooldown System**
**Problem:** Crime cooldown is implemented in CrimeService, but there's no generic cooldown system for other actions.

**Solution:** Create a `CooldownService` that handles:
- Attack cooldowns
- Travel cooldowns
- Crime cooldowns
- Training cooldowns

#### 6. **Inconsistent Money Handling**
**Problem:** Some methods use `addMoney()` / `removeMoney()` directly on Character, others use EconomyService.

**Solution:** Always use EconomyService for money operations to ensure proper logging and validation.

### 🟡 Medium Priority Improvements

#### 7. **Missing Indexes on Database Tables**
**Problem:** Database migrations don't include proper indexes for performance.

**Tables needing indexes:**
```php
// characters table
$table->index('user_id');
$table->index('location_id');
$table->index('faction_id');
$table->index('status');
$table->index('level');

// crime_attempts table
$table->index('character_id');
$table->index('crime_id');
$table->index('attempted_at');
$table->index('success');

// inventories table
$table->index('character_id');
$table->index('item_id');
$table->index('equipped');
```

#### 8. **No Request Validation**
**Problem:** Controllers use manual validation instead of Form Request classes.

**Solution:** Create Form Request classes:
- `app/Http/Requests/Game/AttemptCrimeRequest.php`
- `app/Http/Requests/Game/CharacterDepositRequest.php`
- `app/Http/Requests/Game/CharacterWithdrawRequest.php`
- And others for all user input

#### 9. **Missing Rate Limiting**
**Problem:** No rate limiting on game actions to prevent abuse.

**Solution:** 
- Use Laravel's `throttle` middleware
- Create custom `RateLimitActions` middleware
- Add to config/game.php:
```php
'rate_limits' => [
    'crime_attempts' => 60, // per minute
    'attacks' => 10,        // per minute
    'messages' => 20,       // per minute
],
```

#### 10. **Hardcoded Values**
**Problem:** Some values are hardcoded in services instead of using config.

**Examples:**
- `CrimeService.php` line 69: `0.10` should be `config('game.crime.failure_penalty')`
- Various other magic numbers in services

**Solution:** Move all hardcoded values to `config/game.php`

#### 11. **No API Rate Limiting**
**Problem:** If/when API is added, there's no rate limiting infrastructure.

**Solution:** Use Laravel Sanctum with rate limiting.

#### 12. **Missing Tests**
**Problem:** No unit or feature tests for game logic.

**Solution:** Create comprehensive test suite:
- `tests/Feature/Game/CrimeTest.php`
- `tests/Feature/Game/CharacterTest.php`
- `tests/Feature/Game/CombatTest.php`
- `tests/Unit/Services/CrimeServiceTest.php`
- etc.

### 🟢 Low Priority Improvements

#### 13. **Code Style Consistency**
**Issues:**
- Mixed use of snake_case and camelCase in config keys
- Inconsistent method naming (sometimes `getX`, sometimes `fetchX`)
- Some methods are too long (> 20 lines)

**Solution:** 
- Run `php artisan pint` to auto-format
- Create code style guidelines
- Use consistent naming conventions

#### 14. **Missing DocBlocks**
**Problem:** Some methods lack proper PHPDoc comments.

**Solution:** Add comprehensive DocBlocks for all public methods.

#### 15. **Error Handling**
**Problem:** Some services throw generic `Exception` instead of custom exceptions.

**Solution:** Create custom exceptions:
- `app/Exceptions/GameException.php` (base)
- `app/Exceptions/NotEnoughEnergyException.php`
- `app/Exceptions/CharacterCannotActException.php`
- `app/Exceptions/CooldownException.php`
- etc.

#### 16. **Logging Improvements**
**Problem:** Inconsistent logging approach.

**Solution:** 
- Use Laravel's logging channels
- Create a `GameLogger` service
- Add structured logging for analytics

---

## 🚀 Missing Features (Prioritized)

### 🔴 Phase 1 - Critical (Should be implemented first)

#### 1. **Attack/PvP Combat System**
**Priority:** ⭐⭐⭐⭐⭐  
**Estimated Time:** 2-3 days

**Components needed:**
- `Attack` model and migration
- `CombatService` with damage calculation
- `AttackController` with attack logic
- Hit list system
- Revenge attack tracking
- Hospital/send to hospital on death
- Jail sentence on attack loss
- Attack cooldowns

**Mechanics:**
- Initiative based on speed
- Damage = (strength * 0.5 + weapon_bonus) * (0.8 + random(0, 0.4))
- Critical chance based on dexterity
- Defense reduction based on defense stat
- Money reward for winning (steal % of victim's cash)
- EXP reward for winning/losing

#### 2. **Faction System**
**Priority:** ⭐⭐⭐⭐⭐  
**Estimated Time:** 3-5 days

**Components needed:**
- `Faction` model and migration
- `FactionMember` pivot model
- `FactionRank` model
- `FactionChat` model
- `FactionService`
- `FactionController`
- Faction bank with tax system
- Respect system
- Faction creation requirements (level 10, $10,000)

**Mechanics:**
- Create/join/leave factions
- Faction ranks with permissions
- Faction bank with daily interest
- Faction chat
- Faction crimes (organised crimes)

#### 3. **Mail/Message System**
**Priority:** ⭐⭐⭐⭐  
**Estimated Time:** 1-2 days

**Components needed:**
- `Mail` model and migration
- `MailController`
- Inbox view
- Compose message view
- Read message view
- Delete message functionality
- Unread message count in notification bar

**Fields:**
- sender_id, recipient_id, subject, body, read_at, is_system

#### 4. **Shop System**
**Priority:** ⭐⭐⭐⭐  
**Estimated Time:** 1-2 days

**Components needed:**
- `Shop` model and migration
- `ShopItem` pivot model
- `ShopController`
- Shop view with item listings
- Purchase functionality
- Shop restocking (scheduled command)

**Mechanics:**
- Multiple shops per location
- Different items in different locations
- Restock on schedule
- Dynamic pricing

### 🟡 Phase 2 - Important

#### 5. **Market/Player Trading**
**Priority:** ⭐⭐⭐  
**Estimated Time:** 2-3 days

**Components needed:**
- `MarketListing` model and migration
- `MarketService`
- `MarketController`
- Market listing view
- Purchase from market view
- My listings view

**Mechanics:**
- Players can list items for sale
- Buyers can purchase items
- Market fee (5-10%)
- Listing duration (24-48 hours)
- Cancel listing

#### 6. **Travel System**
**Priority:** ⭐⭐⭐  
**Estimated Time:** 1-2 days

**Components needed:**
- Expand `Location` model
- `TravelService`
- Travel view with map
- Travel cooldowns

**Mechanics:**
- Travel between locations costs energy and money
- Different locations have different items/crimes/shops
- Travel cooldown based on distance
- Location level requirements

#### 7. **Item Crafting**
**Priority:** ⭐⭐⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Recipe` model
- `CraftingService`
- `CraftingController`
- Crafting view

**Mechanics:**
- Combine items to create new items
- Recipes with requirements
- Crafting skill/level requirements
- Success rates

#### 8. **Casino/Gambling**
**Priority:** ⭐⭐⭐  
**Estimated Time:** 2-3 days

**Components needed:**
- `CasinoGame` model
- `Bet` model
- `CasinoService`
- `CasinoController`

**Games to implement:**
- Slots
- Roulette
- Blackjack
- Dice
- Lottery

**Mechanics:**
- House always has slight edge
- Bet amounts
- Win/lose notifications
- Gambling addiction warnings

#### 9. **Daily Login Bonus**
**Priority:** ⭐⭐⭐  
**Estimated Time:** 1 day

**Components needed:**
- Add `last_login_at` to characters table
- Add `login_streak` to characters table
- `DailyBonusService`
- Scheduled command for daily reset
- Login bonus view/notification

**Mechanics:**
- Reward for first login of the day
- Streak bonuses (3 day, 7 day, 30 day)
- Reset on missed day

#### 10. **Achievements/Merits System**
**Priority:** ⭐⭐⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Achievement` model
- `CharacterAchievement` pivot
- `AchievementService`
- Achievement progress tracking

**Mechanics:**
- Unlock achievements for milestones
- Permanent stat bonuses
- Achievement display on profile
- Notification on unlock

### 🟢 Phase 3 - Nice to Have

#### 11. **Faction Wars**
**Priority:** ⭐⭐  
**Estimated Time:** 3-4 days

**Components needed:**
- `FactionWar` model
- `WarAttack` model
- `WarService`
- `WarController`

**Mechanics:**
- Declare war (costs respect)
- War duration (7 days)
- Attack enemy faction members
- Respect gains/losses
- War victory conditions
- War rewards (bank loot)

#### 12. **Territory System**
**Priority:** ⭐⭐  
**Estimated Time:** 3 days

**Components needed:**
- `Territory` model
- `TerritoryControl` model
- `TerritoryService`

**Mechanics:**
- Factions control territories
- Territory provides bonuses
- Territory can be contested
- Territory income
- Territory defense bonuses

#### 13. **Missions/Quests**
**Priority:** ⭐⭐  
**Estimated Time:** 2-3 days

**Components needed:**
- `Mission` model
- `MissionStep` model
- `CharacterMission` pivot
- `MissionService`

**Mechanics:**
- Storyline missions
- Daily missions
- Mission steps
- Mission rewards (money, EXP, items)

#### 14. **Stock Market**
**Priority:** ⭐⭐  
**Estimated Time:** 3 days

**Components needed:**
- `Stock` model
- `Portfolio` model
- `StockHistory` model
- `StockService`

**Mechanics:**
- Buy/sell stocks
- Price fluctuations
- Dividends
- Company information

#### 15. **Properties**
**Priority:** ⭐⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Property` model
- `CharacterProperty` pivot
- `PropertyService`

**Mechanics:**
- Buy/sell properties
- Property income (hourly/daily)
- Property upgrades
- Property types (houses, businesses)

#### 16. **Vehicles**
**Priority:** ⭐⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Vehicle` model
- `CharacterVehicle` pivot
- `VehicleService`

**Mechanics:**
- Buy/sell vehicles
- Vehicle travel speed bonuses
- Vehicle fuel system
- Vehicle combat bonuses

#### 17. **Bounties/Hit Contracts**
**Priority:** ⭐⭐  
**Estimated Time:** 1-2 days

**Components needed:**
- `Bounty` model
- `BountyService`
- `BountyController`

**Mechanics:**
- Place bounty on player
- Bounty amount
- Claim bounty by attacking target
- Bounty expiration
- Bounty leaderboard

#### 18. **Marriage/Partnerships**
**Priority:** ⭐  
**Estimated Time:** 1 day

**Components needed:**
- `Marriage` model
- `MarriageService`

**Mechanics:**
- Propose marriage
- Accept/reject proposals
- Marriage bonuses
- Divorce system

### 🔵 Phase 4 - Advanced Features

#### 19. **Drug System**
**Priority:** ⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Drug` model (or use Item type)
- `DrugEffect` model
- `DrugService`

**Mechanics:**
- Temporary stat boosts
- Addiction system
- Overdose penalties
- Withdrawal effects

#### 20. **Loan System**
**Priority:** ⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Loan` model
- `LoanService`

**Mechanics:**
- Borrow money
- Interest rates
- Repayment schedules
- Late fees
- Default penalties

#### 21. **Education System**
**Priority:** ⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Course` model
- `Enrollment` model
- `EducationService`

**Mechanics:**
- Enroll in courses
- Course duration (real time)
- Permanent stat boosts
- Course requirements

#### 22. **Job System**
**Priority:** ⭐  
**Estimated Time:** 2 days

**Components needed:**
- `Job` model
- `JobApplication` model
- `JobService`

**Mechanics:**
- Apply for jobs
- Daily pay
- Skill XP
- Job requirements

#### 23. **Real-time Chat**
**Priority:** ⭐  
**Estimated Time:** 2-3 days

**Components needed:**
- Laravel Echo setup
- Pusher/Ably integration
- `ChatMessage` model
- `ChatService`
- Frontend Vue/React components

**Mechanics:**
- Global chat
- Faction chat
- Private messages
- Chat moderation

#### 24. **Leaderboards**
**Priority:** ⭐  
**Estimated Time:** 1-2 days

**Components needed:**
- `Leaderboard` model
- `LeaderboardService`
- Scheduled command for updates
- Leaderboard views

**Categories:**
- Level
- Money
- Respect
- Crimes committed
- Attacks won
- Faction rank

#### 25. **Events System**
**Priority:** ⭐  
**Estimated Time:** 2 days

**Components needed:**
- `GameEvent` model
- `EventService`

**Mechanics:**
- Holiday events
- Double XP weekends
- Special crimes
- Event rewards

#### 26. **Referral System**
**Priority:** ⭐  
**Estimated Time:** 1 day

**Components needed:**
- `Referral` model
- `ReferralService`

**Mechanics:**
- Referral codes
- Referral rewards
- Referral tracking

#### 27. **Admin Panel**
**Priority:** ⭐⭐  
**Estimated Time:** 3-5 days

**Components needed:**
- Nova or custom admin
- User management
- Item management
- Crime management
- Game settings
- Moderation tools

**Features:**
- Ban/mute users
- Edit items/crimes
- Game configuration
- Player support

#### 28. **Moderation Tools**
**Priority:** ⭐⭐  
**Estimated Time:** 2 days

**Components needed:**
- `ModerationLog` model
- `ModerationService`

**Features:**
- Warn users
- Temporary bans
- Permanent bans
- Mute chat
- Freeze accounts

#### 29. **API for Mobile**
**Priority:** ⭐  
**Estimated Time:** 3-5 days

**Components needed:**
- Sanctum setup
- API routes
- API resources
- Authentication

#### 30. **Web Push Notifications**
**Priority:** ⭐  
**Estimated Time:** 2 days

**Components needed:**
- Service worker
- Push notification service
- User subscription management

**Notifications for:**
- Energy full
- Cooldown expired
- Jail release
- Hospital release
- New messages
- Attacked by someone

---

## 📋 Implementation Roadmap

### Week 1-2: Core Gameplay Completion
1. **Day 1-2:** Implement Attack/PvP system
2. **Day 3-5:** Implement Faction system
3. **Day 6:** Implement Mail system
4. **Day 7:** Implement Shop system

### Week 3-4: Economy & Social
5. **Day 8-9:** Implement Market/Player trading
6. **Day 10:** Implement Travel system
7. **Day 11-12:** Implement Casino/gambling
8. **Day 13:** Implement Daily login bonus
9. **Day 14:** Implement Achievements system

### Week 5-6: Advanced Features
10. **Day 15-16:** Implement Faction Wars
11. **Day 17-18:** Implement Territory system
12. **Day 19-20:** Implement Missions/Quests
13. **Day 21:** Implement Stock Market
14. **Day 22:** Implement Properties
15. **Day 23:** Implement Vehicles

### Week 7-8: Polish & Scale
16. **Day 24-25:** Implement Bounties
17. **Day 26:** Implement Marriage
18. **Day 27-28:** Implement Admin Panel
19. **Day 29:** Implement Moderation Tools
20. **Day 30:** Testing and bug fixes

### Week 9+: Optional Features
- Drug system
- Loan system
- Education system
- Job system
- Real-time chat
- Leaderboards
- Events system
- Referral system
- API for Mobile
- Web Push Notifications

---

## 🎯 Quick Wins (Can be implemented in < 1 day)

Based on the existing codebase, these features can be implemented quickly:

1. **Daily Login Bonus** - Just needs `last_login_at` column and a check on login
2. **Merit/Achievement Badges** - Use existing activity log data
3. **Gambling Mini-game** - Simple dice roll using existing money logic
4. **Player Profile Pages** - Read-only view of character stats
5. **Consumable Items with Effects** - Extend existing Item model with effect fields
6. **Friends/Enemy List** - Simple relationship table
7. **Cooldown Notifications** - Use existing notification system
8. **Item Categories** - Extend ItemType enum

---

## 🛠️ Technical Debt Priority

### Immediate (Fix before adding new features)
1. **Service Dependency Injection** - Fix the `new Service()` pattern
2. **Circular Dependencies** - Resolve EconomyService dependencies
3. **Attack System** - Implement basic PvP
4. **Cooldown System** - Create generic cooldown service
5. **Request Validation** - Create Form Request classes

### Short-term (Fix within next 2 weeks)
6. **Database Indexes** - Add missing indexes
7. **Rate Limiting** - Implement action rate limiting
8. **Hardcoded Values** - Move to config
9. **Custom Exceptions** - Better error handling
10. **Tests** - Add unit/feature tests

### Long-term (Fix before production)
11. **Code Style** - Consistent formatting
12. **DocBlocks** - Complete documentation
13. **Logging** - Structured logging
14. **Caching** - Implement caching for leaderboards, etc.
15. **Performance Optimization** - Query optimization

---

## 📊 Feature Comparison with Competitors

### What Torn City Has That We Need
- [ ] Attacking other players
- [ ] Mugging
- [ ] Bounties/Hit contracts
- [ ] Revenge attacks
- [ ] War mode/Gang wars
- [ ] Escape from jail
- [ ] Item market/P2P trading
- [ ] Stock market
- [ ] Businesses
- [ ] Drug mechanics
- [ ] Loan sharks
- [ ] Casino/Gambling
- [ ] Points/Premium currency
- [ ] Gangs/Factions/Families
- [ ] Gang crimes
- [ ] Messaging system
- [ ] Forums/Bulletin boards
- [ ] Friends list/Enemy list
- [ ] Profile pages
- [ ] Marriage/Partnerships
- [ ] Nerve/Action points
- [ ] Gym/Training
- [ ] Education system
- [ ] Job/Working
- [ ] Merit badges/Achievements
- [ ] Rank/Prestige system
- [ ] Happy stat
- [ ] Travel/City system
- [ ] Item crafting
- [ ] Temporary consumables
- [ ] Weapon/armor enhancement
- [ ] Car/Vehicle system
- [ ] Passive income timers
- [ ] Daily login bonus
- [ ] Cooldown notifications
- [ ] Events/Seasonal content

### What We Have That's Better
- [x] **Modern Tech Stack** - Laravel 12, Tailwind CSS, Alpine.js
- [x] **Clean Architecture** - Well-organized services and models
- [x] **Transparent Probabilities** - Show success rates (can be extended)
- [x] **Configurable Mechanics** - Everything in config/game.php
- [x] **Comprehensive Logging** - ActivityLog tracks everything
- [x] **Type Safety** - PHP 8.3 with proper typing
- [x] **Enum Support** - Proper enum usage for game states

---

## 🎨 UI/UX Improvements

### Immediate
1. **Add cooldown timers** on action buttons
2. **Show success probabilities** for crimes
3. **Add progress bars** for EXP, energy, health, nerve
4. **Improve mobile responsiveness**
5. **Add keyboard shortcuts** for common actions

### Short-term
6. **Dark mode** toggle
7. **Sound effects** for actions
8. **Animations** for combat, level ups, etc.
9. **Tooltips** for game mechanics explanation
10. **Tutorial** for new players

### Long-term
11. **Custom themes**
12. **Avatar system**
13. **Map visualization** for travel
14. **Inventory sorting/filtering**
15. **Quick action buttons** on dashboard

---

## 🔧 Configuration Improvements

### Add to config/game.php

```php
// Attack system
'attack' => [
    'base_damage' => 5,
    'damage_variation' => 0.20,
    'crit_chance' => 0.10,
    'crit_multiplier' => 2.0,
    'defense_reduction' => 0.5,
    'min_damage' => 1,
    'attack_cooldown' => 300, // 5 minutes
    'hit_list_cost' => 5000,
    'mug_chance' => 0.30, // 30% chance to mug instead of hospitalize
    'mug_percent' => 0.20, // Steal 20% of victim's cash
],

// Faction system
'factions' => [
    'create_cost' => 10000,
    'create_level' => 10,
    'max_members' => 50,
    'respect_per_win' => 10,
    'respect_per_loss' => -5,
    'bank_tax' => 0.05,
    'war_cost' => 5000, // Respect cost to declare war
    'war_duration' => 604800, // 7 days in seconds
    'max_ranks' => 10,
],

// Travel system
'travel' => [
    'base_cost' => 100,
    'cost_per_level' => 10,
    'energy_cost' => 5,
    'cooldown_base' => 60, // 1 minute
    'cooldown_per_level' => 30, // +30 seconds per level difference
],

// Rate limits
'rate_limits' => [
    'crime_attempts' => 60, // per minute
    'attacks' => 10, // per minute
    'messages' => 20, // per minute
    'market_listings' => 10, // per minute
],

// Daily bonuses
'daily' => [
    'login_reward' => 1000, // Money
    'login_exp' => 50, // EXP
    'streak_3_reward' => 5000,
    'streak_7_reward' => 15000,
    'streak_30_reward' => 50000,
],

// Casino
'casino' => [
    'house_edge' => 0.05, // 5%
    'min_bet' => 100,
    'max_bet' => 100000,
],
```

---

## 📈 Performance Considerations

### Database Optimization
1. **Add indexes** to all foreign key columns
2. **Cache frequently accessed data**:
   - Character stats (1 minute cache)
   - Leaderboards (5-10 minute cache)
   - Shop items (1 hour cache)
3. **Use eager loading** for relationships in controllers
4. **Paginate** all lists (crimes, inventory, etc.)
5. **Optimize queries** with proper selects and where clauses

### Queue Optimization
1. **Separate queues** for different job types:
   - High priority: energy regen, health regen
   - Medium priority: notifications, logging
   - Low priority: daily interest, cleanup
2. **Use database queue** for development, Redis for production
3. **Monitor queue performance** with Horizon

### Caching Strategy
1. **Redis** for session and cache
2. **Cache tags** for invalidation
3. **Cache warmup** on deploy

---

## 🔒 Security Considerations

### Immediate
1. **Rate limiting** on all game actions
2. **Input validation** for all user input
3. **CSRF protection** (Laravel default)
4. **SQL injection prevention** (Eloquent ORM)
5. **XSS protection** (Blade escaping)

### Short-term
6. **Two-factor authentication** for admin accounts
7. **Password complexity requirements**
8. **Account lockout** after failed login attempts
9. **IP tracking** for moderation
10. **Session security** settings

### Long-term
11. **HTTPS enforcement**
12. **Security headers** (CSP, X-Frame-Options, etc.)
13. **Regular backups**
14. **Audit logging** for admin actions
15. **Fail2Ban** for brute force protection

---

## 🎓 Learning Resources

### Laravel
- [Laravel Documentation](https://laravel.com/docs)
- [Laravel News](https://laravel-news.com/)
- [Laracasts](https://laracasts.com/)

### Game Development
- [Text-Based Game Design](https://gamedev.net/forums/forum/12-gamedesign/)
- [MUD/MMO Architecture](https://www.mudconnect.net/)

### Competitor Analysis
- [Torn City](https://www.torn.com/)
- [Omerta Game](https://www.omertagame.com/)

---

## 📝 Next Steps

### For the Development Team

1. **Review this document** and prioritize based on your needs
2. **Start with Quick Wins** - Implement features that can be done in < 1 day
3. **Fix Technical Debt** - Especially service injection and circular dependencies
4. **Implement Core Features** - Attack system, Factions, Mail, Shops
5. **Test Thoroughly** - Each feature before moving to the next
6. **Document** - Keep this document updated as you implement features

### For the Project Lead

1. **Set Milestones** - Use GitHub/GitLab milestones to track progress
2. **Assign Tasks** - Use issues to track individual features
3. **Code Reviews** - Ensure quality with pull requests and reviews
4. **Regular Testing** - Manual and automated testing
5. **Community Feedback** - Get player feedback on new features

---

## 📊 Success Metrics

### Player Retention
- Daily Active Users (DAU)
- Monthly Active Users (MAU)
- Average session duration
- Return rate (players coming back)

### Engagement
- Average actions per session
- Average crimes committed per day
- Average attacks per day
- Average playtime per day

### Economy
- Total money in circulation
- Bank balance distribution
- Market activity
- Casino profits

### Community
- Faction count
- Average faction size
- Chat activity
- Forum posts

---

**Document Version:** 1.0  
**Last Updated:** 2026-07-04  
**Next Review:** After Phase 1 completion