Troop Tracker is the Empire’s official operations dashboard, engineered to impose order upon trooper assignments, moderation workflows, and hierarchical communications across organizations, regions, and units. Forged with Laravel, Blade, Bootstrap 5, HTMX, and Alpine‑driven JavaScript, it delivers the precision, discipline, and ruthless efficiency expected of any system operating under Imperial authority.
This project remains under active development, which is to say it currently exists in a state of sanctioned chaos. Features may appear, disappear, or behave unpredictably without prior notice, as is their prerogative during this phase of imperial construction. Should you encounter bugs, inconsistencies, or architectural decisions that defy mortal comprehension, rest assured they are merely temporary artifacts of progress. Proceed with caution, submit issues with appropriate deference, and remember: stability will arrive when it is commanded to arrive, and not a moment sooner.
Progress continues at a pace deemed acceptable by the Empire. New features, refinements, and the occasional miracle will be deployed as they reach a state worthy of consumption. Garrison Liasons are encouraged to return in approximately one month to witness the next phase of sanctioned advancement. Until then, patience is not only advised — it is expected.
Update Feb 18th: Despite rumors to the contrary, progress has not stalled. In fact, the project currently stands at an estimated 85% operational readiness, supported by a test suite now exceeding 2,000 trials of loyalty. Minor rebellions within the codebase are being suppressed with appropriate vigor. Observers may take this as a sign that stability is approaching, though only the Empire may determine when "approaching" becomes "arrived." Sensible personnel are advised to check back in roughly one month for the next sanctioned update, assuming the system has not evolved beyond the need for such courtesies.
Update Mar 8th: Troop Tracker edges ever closer to UAT, with performance‑rebellious tests being rewritten, optimized, and reminded of their place in the hierarchy; work continues on the configurable XenForo integration, ensuring it can ultimately operate either as a seamless Imperial fusion or a proudly isolationist standalone deployment; and the visual command interfaces have been refreshed with updated Stormtrooper, Bounty Hunter, Rebel, Clone, and Sith themes, each calibrated for maximum intimidation, usability, or in the case of Rebels, remedial hand‑holding — overall, stability is rising, features are aligning, and the system marches toward UAT with the slow, inevitable certainty of an Imperial Star Destroyer entering orbit.
Troop Tracker follows Action-Domain-Responder (ADR) with Command/Query Separation via MagicBus. Controllers orchestrate, handlers execute business logic, responses render results.
Key Patterns:
- MagicBus: Convention-based dispatcher routes Commands (writes) and Queries (reads) to handlers
- Feature Organization: Business logic grouped by domain in
app/Features/(Events, Troopers, Organizations, Reports, Notices, Changes) - Auto-Generated Models: Base models in
app/Models/Base/(never edit), extended inapp/Models/ - HTMX + Alpine: Progressive enhancement for dynamic UI without full page reloads
- Queue Processing: Background jobs orchestrate handlers via MagicBus
Read full architecture documentation →
tracker-app/ - The Laravel application (run all commands from here)
- Complete Laravel 12.x source, tests, and dependencies
- See Project Structure for internal organization
docs/ - Project documentation
- Architecture, database schema, authentication flows, coding conventions
- See Documentation Guide for reading order
Root Files - README.md, CODE_OF_CONDUCT.md, CONTRIBUTING.md, GitHub Actions
- Hierarchical Access Control: Strict Organization → Region → Unit permissions with automatic inheritance and scoped visibility via authorization policies
- Trooper Management: Multi‑organization membership, role‑based permissions (member/moderator/administrator), notification preferences, costume tracking, and achievement badges
- Event & Shift Management: Full event lifecycle (draft/open/closed/cancelled), multi‑shift scheduling, organization-specific invitations, trooper signup tracking (going/tentative/unavailable)
- Real‑Time HTMX Interactions: Instant UI updates for sign‑ups, cancellations, costume changes, and shift displays without full page reloads
- Smart Notifications: Configurable frequency (never/instant/daily), event creation/cancellation emails, daily digest aggregation
- Awards & Recognition: Organization-based awards with frequency controls (once/monthly/yearly), multi-recipient support
- Notice System: Organization-scoped announcements with read tracking and type-based styling (info/warning/alert)
- Event Photo Gallery: Photo uploads with trooper tagging, large/thumbnail variants, administrative photo flags
- MagicBus Command/Query Pattern: Automatic handler resolution, Commands for writes, Queries for reads
- Feature-Organized Code: Domain logic grouped by business area
- Component-Driven Blade: PHP 8.2+ with server-rendered templates
- Progressive Enhancement: Bootstrap 5.2x + HTMX 2.x + Alpine 3.x
- Auto-Generated Models: MySQL with Reliese Laravel base model generation
- Comprehensive Testing: Feature tests (Controllers/Jobs/Commands), Unit tests (Handlers/Services)
- Policy-Based Authorization: Scoped access control for all resources
- Audit Trail: Polymorphic change tracking with trooper stamps
- PHP 8.x+ with strict types and scalar type hints
- Laravel 12.x with Breeze authentication
- Database: MySQL (production), SQLite (testing)
- Frontend: Blade templates + Bootstrap 5.2x + HTMX 2.x + Alpine 3.x
- Queue: Database-backed Laravel queue
- Mail: Laravel mailable classes with queue support
- Testing: PHPUnit with Feature/Unit test separation
- Models: Auto-generated via Reliese Laravel
Get operational in under 5 minutes. All commands run from the tracker-app/ directory.
# Clone and navigate to the Laravel app directory
git clone https://github.com/obsidianslicers/trooper-tracker.git
cd trooper-tracker/tracker-app
# Install PHP and JavaScript dependencies
composer install
npm install
# Configure environment
cp .env.example .env
php artisan key:generateConfigure your .env file - See Environment Variables for complete reference:
- Set database credentials
- Add OAuth keys if testing Google/XenForo login (optional for basic development)
- Queue driver defaults to
database
# Set up database with sample data
php artisan migrate
php artisan db:seed --class=OrganizationSeeder
php artisan db:seed --class=ActorSeeder
# Start development servers (requires 3 terminals)
php artisan serve # Terminal 1: Laravel app (http://localhost:8000)
npm run dev # Terminal 2: Vite asset compilation
php artisan queue:work # Terminal 3: Background job processingDefault Login:
- Check ActorSeeder for admin credentials or create a new account
- All new accounts require admin approval (approve via database or create as active)
# Run full test suite (Feature + Unit)
composer test:freshdb # just once is all it takes
php artisan test
# Run with coverage report
#php artisan test --coverage
# Run specific test file
#php artisan test tests/Feature/Http/Controllers/Events/EventDisplayControllerTest.phpBefore submitting PRs:
- New/Updated Code must be tested
- All tests must pass:
php artisan test - Code must pass formatting:
composer pint:format - Code must pass static analysis:
composer stan - Follow conventions in
docs/CODING_CONVENTIONS.md
# Generate base models after schema changes
php artisan code:models
php artisan tracker:generate-factories
# Run scheduled tasks manually
php artisan tracker:send-daily-event-notifications
php artisan tracker:close-events
php artisan tracker:calculate-trooper-achievements
# Clear caches during development
php artisan config:clear
php artisan route:clear
php artisan view:clearRead the documentation in this order for maximum comprehension efficiency.
Start here - Essential reading before writing code:
- Architecture - ADR, MagicBus, Command/Query patterns, domain organization, testing strategy
- Coding Conventions - Naming conventions, code style, architectural standards
- Project Structure - Directory layout and file organization
- Database Schema - Table reference, relationships, ERD
Recommended for all contributors:
- Cheat Sheet - Quick reference for Artisan commands and workflows
- VSCode Extensions - Recommended editor setup
Consult these when working on specific subsystems:
- Authentication - Multi-provider auth and registration pipeline
- Notifications - Event notification system (instant/daily/cancellations)
- XenForo OAuth - Forum integration via OAuth2
- Environment Variables - Complete
.envconfiguration reference - Deployment Guide - Production server setup and deployment procedures
- Composer Dependencies - PHP package reference
- NPM Dependencies - Frontend package reference
- Contributing Guide - Submission workflow, PR requirements, code review process
- Code of Conduct - Community standards and enforcement
Contributions are accepted and processed with the efficiency expected of Imperial operations. Review the Contributing Guide for submission protocols, then consult Coding Conventions for architectural requirements. All contributions must pass automated testing and code style validation before consideration.