ROADMAP.md

Bloodbullets Roadmap

This roadmap turns the current high-level recommendations into a concrete implementation plan for the repo.

Goal

Improve Bloodbullets in three areas:

1. Player acquisition and first-session retention
2. Repeat engagement and return rates
3. Technical maintainability and operational safety

Top 10 Code Changes

1. Rebuild the homepage into a real acquisition funnel

Problem: The public homepage is almost empty and does not explain why a new player should register, what the game loop is, or what to do first.

Primary files:

• public_html/src/Controllers/index.php
• public_html/src/Views/index.twig
• public_html/app/Resources/Views/base.twig

Implementation:

• Add a clear hero section with value proposition, registration CTA, and login CTA
• Add a short "How it works" section for crimes, growth, family, and competition
• Add social proof sections such as active players, screenshots, and core features
• Add a direct route from landing page to registration and starter flow

Success metric:

• Higher register conversion from homepage visits

2. Expand onboarding into a stronger first-session questline

Problem: The onboarding system already exists, but it mainly introduces navigation. It should guide players into the first satisfying gameplay loop.

Primary files:

• public_html/src/Business/OnboardingService.php
• public_html/src/Data/OnboardingDAO.php
• public_html/src/Controllers/game/status.php
• public_html/src/Controllers/game/members.php
• public_html/src/Controllers/game/missions.php
• public_html/src/Business/CrimeService.php
• public_html/src/Business/UserService.php
• public_html/src/Views/game/status.twig

Implementation:

• Add more meaningful starter steps such as:
• First reward claim
• First market interaction
• First equipment purchase
• First friend or family interaction
• First daily challenge completion
• Add a visible end-of-onboarding bonus
• Add a "next best action" explanation on the status page

Success metric:

• More players complete 3 or more onboarding steps in their first session

3. Add milestone analytics instead of only page analytics

Problem: The analytics foundation is already present, but the most useful product questions are about behavior milestones, not just page traffic.

Primary files:

• public_html/src/Business/AnalyticsService.php
• public_html/src/Data/AnalyticsDAO.php
• public_html/src/Controllers/Ajax/analytics.track.php
• Gameplay services that complete important actions

Implementation:

• Track milestone events such as:
• register_complete
• first_crime
• first_training
• joined_family
• daily_challenge_completed
• returned_day_2
• returned_day_7
• Track drop-off points in onboarding
• Build admin views around milestone conversion rather than just page views

Success metric:

• Clear visibility into where new players churn

4. Refactor the daily cron into focused services

Problem: day.php handles too many unrelated concerns in one file, making balancing and debugging risky.

Primary files:

• public_html/app/cronjob/day.php
• New service files under public_html/src/Business/ or public_html/src/Business/Logic/

Implementation:

• Split daily work into separate units:
• Account cleanup service
• Retention email service
• Seasonal event service
• Economy reset service
• Daily challenge rotation service
• Moderation scan service
• Demo account reset service
• Add logging around each job section

Success metric:

• Safer daily deployments and faster debugging when cron issues occur

5. Redesign the daily challenge system for balance and clarity

Problem: The daily challenge rotation and payout logic are powerful but hard to reason about and tune.

Primary files:

• public_html/app/cronjob/day.php
• public_html/src/Data/DailyChallengeDAO.php
• public_html/src/Entities/DailyChallenge.php
• public_html/src/Views/game/daily-challenges.twig

Implementation:

• Move challenge generation rules into a dedicated service
• Replace hardcoded reward logic with clearer config or DB-backed values
• Group challenges by category and intended player segment
• Show players clearer progress and streak rewards
• Add "almost complete" and "come back today" messaging

Success metric:

• Higher daily challenge completion rate

6. Improve reactivation and comeback retention

Problem: There is already a 6-month inactive reminder, but it should be part of a broader reactivation strategy.

Primary files:

• public_html/app/cronjob/day.php
• public_html/src/Controllers/inactive-reminder-unsubscribe.php
• Mail template logic in the cron file or new email service

Implementation:

• Create staged reactivation windows such as 7 days, 30 days, 90 days, and 180 days
• Tailor copy and rewards by inactivity length
• Add one-click return links where appropriate
• Track reactivation success rates

Success metric:

• More dormant users return after reminder campaigns

7. Replace brittle moderation heuristics with a safer review flow

Problem: The current blacklisted-word scan is too simple and likely to cause false positives or be bypassed.

Primary files:

• public_html/app/cronjob/day.php
• Message and moderation-related services and admin pages

Implementation:

• Move scanning into a dedicated moderation service
• Normalize message text before checks
• Add an admin review queue instead of only incrementing reports
• Add logging so moderators can see why something was flagged

Success metric:

• Fewer false positives and better moderation visibility

8. Redesign the status page around "what should I do next?"

Problem: The status page contains valuable information, but it is dense and does not prioritize the next rewarding action.

Primary files:

• public_html/src/Views/game/status.twig
• public_html/src/Controllers/game/status.php
• public_html/app/Resources/Views/gamebase.twig

Implementation:

• Add a top summary card with:
• Ready actions
• Expiring opportunities
• Next onboarding step
• Best next action based on cooldowns and account state
• Reduce cognitive load for new players
• Improve mobile readability

Success metric:

• More action clicks from the status page

9. Modernize key frontend interactions

Problem: Some frontend interactions are outdated or inconsistent with modern browser behavior.

Primary files:

• public_html/src/Views/game/status.twig
• public_html/web/public/js/
• Shared Twig base templates

Implementation:

• Replace deprecated document.execCommand("copy") with navigator.clipboard
• Reduce inline page-specific JavaScript where practical
• Improve mobile responsiveness in high-traffic pages
• Standardize action feedback and loading states

Success metric:

• Better mobile experience and fewer UX rough edges

10. Do a safety and production-hardening pass

Problem: The repo already acknowledges security and operational risk. Before growth work scales up traffic, core systems need hardening.

Primary files:

• README.md
• SECURITY.md
• Session, auth, admin, and cron-related files across the repo

Implementation:

• Add better cron logging and failure visibility
• Review account deletion safety
• Review session and cookie handling
• Add more audit trails for admin and automated actions
• Prioritize protections around sensitive flows before growth campaigns

Success metric:

• Lower operational risk and safer production changes

Suggested Delivery Order

Phase 1: First-session retention

Focus:

• Homepage
• Onboarding
• Status page guidance
• Milestone analytics

Outcome:

• More players understand the game and stick through the first session

Phase 2: Repeat engagement

Focus:

• Daily challenges
• Reactivation campaigns
• Better reward loops

Outcome:

• More players return on day 2, day 7, and beyond

Phase 3: Maintainability and safety

Focus:

• Cron refactor
• Moderation refactor
• Frontend cleanup
• Security and ops hardening

Outcome:

• Faster iteration and lower risk during future feature work

Recommended First 30 Days

Week 1

• Rebuild public_html/src/Views/index.twig
• Add clearer registration funnel and feature explanation

Week 2

• Expand onboarding steps in public_html/src/Business/OnboardingService.php
• Improve onboarding UI in public_html/src/Views/game/status.twig

Week 3

• Add milestone analytics events
• Create an admin view for onboarding conversion and first-session progression

Week 4

• Extract daily challenge generation from public_html/app/cronjob/day.php
• Start splitting cron logic into smaller services

Immediate Priorities

If only three things are tackled first, start with these:

1. Homepage rebuild
2. Onboarding expansion
3. Analytics milestone tracking

Those three changes should produce the clearest short-term gain in player retention while also giving better data for future decisions.