Pulse-Engine

Architecture

src/
├── Config/ VotingConfig — typed, immutable config value object
├── Contract/ All interfaces (Database, Cache, Repositories, Payment, Events, RateLimiter)
├── DTO/ Immutable command + result objects (CastVoteCommand, VoteResult, ...)
├── Entity/ Rich domain entities (Contestant, VoteRecord, PaymentRecord)
├── Enum/ PHP 8.1 enums (VoteStatus, ContestantStatus, PaymentStatus)
├── Event/ Domain events + NullEventDispatcher
├── Exception/ Typed exception hierarchy rooted at PulseEngineException
├── Factory/ VoteServiceFactory — wires the full object graph
├── Migration/ SQL migrations + MigrationRunner
├── Repository/ Concrete PDO-backed repository implementations
├── Security/ RateLimiter (cache-backed) + IntegrityGuard (HMAC)
└── Service/ VoteService · PaymentService · PricingEngine · SubscriptionService

Quick Start (no DI container)

use AlfaCode\PulseEngine\Config\VotingConfig;
use AlfaCode\PulseEngine\DTO\CastVoteCommand;
use AlfaCode\PulseEngine\Factory\VoteServiceFactory;
$config = VotingConfig::fromFile(__DIR__ . '/config/voting_config.php');
$voteService = VoteServiceFactory::createVoteService($db, $cache, $config);
$result = $voteService->castFreeVote(new CastVoteCommand(
 userId: $userId,
 contestantId: $contestantId,
 editionId: $editionId,
 ipAddress: $_SERVER['REMOTE_ADDR'],
 userAgent: $_SERVER['HTTP_USER_AGENT'] ?? '',
));
echo "Vote #{$result->voteId} cast. New total: {$result->newVoteTotal}";

Paid Votes Flow

use AlfaCode\PulseEngine\DTO\PurchaseVotesCommand;
use AlfaCode\PulseEngine\Factory\VoteServiceFactory;
$paymentService = VoteServiceFactory::createPaymentService(
 $db, $cache, $config, $paystackProvider
);
// Step 1 — Initiate: returns a redirect URL
$redirectUrl = $paymentService->initiate(
 new PurchaseVotesCommand(
 userId: $userId,
 contestantId: $contestantId,
 editionId: $editionId,
 voteCount: 50,
 ipAddress: $ip,
 callbackUrl: 'https://yourapp.com/payment/callback',
 ),
 userEmail: $user->email,
);
// Step 2 — Verify (on callback / webhook)
$voteResult = $paymentService->verifyAndApply($reference, $ip);

Migrations

001_create_vote_editions.sql
002_create_vote_contestants.sql
003_create_vote_voting.sql
004_create_vote_payments.sql
005_create_vote_audit_log.sql

use AlfaCode\PulseEngine\Migration\MigrationRunner;
$runner = new MigrationRunner($db, __DIR__ . '/src/Migration');
$runner->run(); // apply pending
$runner->rollback(1); // undo last migration

Extending

Configuration

$config = VotingConfig::fromFile('/etc/pulse-engine/config.php');

Tests

composer install
vendor/bin/phpunit

License