⚡ Volt R² Framework

🇺🇸 English Version | 🇧🇷 Versão em Português

---

🇺🇸 English Version

Volt R² is a custom-built, asynchronous PHP mini-framework designed to run within persistent in-memory environments using the RoadRunner application server. Instead of traditional PHP architectures that bootstrap the entire application on every HTTP request, Volt R² keeps the HTTP Kernel and its primary dependencies alive in memory to eliminate bootstrap overhead.

🗺️ Origin & Evolution

Volt R² was built based on the practical architecture lessons and reverse engineering of the BananaClub project. After identifying decoupling challenges and infrastructure bottlenecks in a conventional MVC environment, the foundation was restructured from scratch. The goal was to isolate the business logic into components and migrate the runtime to an asynchronous in-memory model with RoadRunner.

🛠️ Architectural Features (Core)

The framework was built from scratch adhering to SOLID principles and Clean Architecture guidelines:

• DI Container (Inversion of Control): Dependency manager featuring Auto-wiring via Reflection API.
• HTTP Kernel & Native CLI: Decoupled handling of web requests and custom terminal commands.
• Flexible Routing & Middleware: Structured pipeline for request interception and manipulation.
• Fluent Query Builder: Lightweight and fast database abstraction layer built to prevent SQL Injection.
• Built-in Rate Limiter: Native component to restrict request rates and prevent API abuse.
• Core Security: Native middleware layers for CSRF protection and strict data handling.

🔌 Native Drivers & Integrations

Volt R² includes built-in drivers designed to facilitate SaaS product development:

• 🧠 Artificial Intelligence (Gemini API): Native SDK for prompt handling and automated language processing tasks.
• 💳 Digital Payments (Stripe API): Ready-to-use infrastructure for processing transactions and receiving financial webhooks.
• 🚗 Cache & Sessions (Redis): Fast state management to maintain session consistency across asynchronous RoadRunner workers.
• 📧 Communication (Resend): Integrated driver for transactional email delivery.
• 🔑 Social Authentication (Google OAuth): Simplified flow for secure third-party user onboarding.
• 🎯 Observability (Sentry): Native exception handling integration for tracking errors and logging in real time.

💻 Command Line Interface (Volt CLI)

The framework features its own CLI (./volt) developed to speed up development scaffolding and manage database schemas:

• php volt make:controller — Automated generation of decoupled controllers.
• php volt make:migration — Creates migration files with native timestamps.
• php volt migrate — Sequential execution of pending migrations.
• php volt rollback — Reverts the last batch of database changes.
• php volt make:context & make:context-total — Custom utility commands to aggregate application context files.

🧪 Code Quality & Automated Testing

To ensure the stability of applications running in persistent memory, Volt R² was developed with strict typing and static analysis:

• Automated Tests (PHPUnit): Unit and integration test suite covering the DI Container, Query Builder, Router, Rate Limiter, and Session flows.
• Static Analysis (PHPStan): Core codebase strictly analyzed and fully validated at PHPStan Level 9.

---

🇧🇷 Versão em Português

O Volt R² é um miniframework PHP próprio e assíncrono, projetado para rodar em ambientes residentes em memória utilizando o RoadRunner. Ao contrário do modelo tradicional do PHP, onde a aplicação é inicializada e encerrada a cada requisição, o Volt R² mantém o Kernel e suas dependências vivas em memória para eliminar o overhead de bootstrap.

🗺️ Origem e Evolução

O Volt R² nasceu da evolução prática e da engenharia do projeto BananaClub. Após identificar os padrões arquiteturais, desafios de desacoplamento e gargalos tradicionais de infraestrutura em um ambiente MVC convencional, a fundação foi reestruturada do zero. O objetivo foi isolar a lógica de negócio em componentes puros e migrar a execução para um modelo assíncrono em memória com o RoadRunner.

🛠️ Recursos de Arquitetura (Core)

O framework foi construído do zero respeitando os princípios SOLID e diretrizes de Clean Architecture:

• Container DI (Inversão de Controle): Gerenciador de dependências com suporte a Auto-wiring via Reflection API.
• Kernel Http & CLI Nativa: Tratamento desacoplado de requisições web e comandos customizados via terminal.
• Routing Flexível & Middlewares: Pipeline estruturado para interceptação e manipulação de requisições.
• Query Builder Fluente: Abstração de banco de dados leve e rápida, estruturada contra SQL Injection.
• Rate Limiter Embutido: Proteção nativa contra abusos de endpoints e limitação de taxa de requisições.
• Segurança Core: Middlewares nativos para proteção contra CSRF e manipulação estrita de dados.

🔌 Integrações Nativas (Drivers)

O Volt R² já nasce preparado para facilitar o desenvolvimento de produtos digitais (SaaS), trazendo drivers integrados:

• 🧠 Inteligência Artificial (Gemini API): SDK nativo para engenharia de prompts e tarefas de processamento de linguagem.
• 💳 Economia Digital (Stripe API): Infraestrutura pronta para processamento de transações e recepção de eventos via Webhooks.
• 🚗 Cache e Sessões (Redis): Gerenciamento de estado rápido para manter a consistência entre workers assíncronos do RoadRunner.
• 📧 Comunicação (Resend): Driver integrado para disparos de e-mails transacionais.
• 🔑 Autenticação Social (Google OAuth): Fluxo simplificado para login seguro de usuários.
• 🎯 Observabilidade (Sentry): Integração nativa do tratador de exceções para captura e rastreamento de bugs em tempo real.

💻 Interface de Linha de Comando (Volt CLI)

O framework conta com uma CLI própria (./volt) desenvolvida nativamente para acelerar o fluxo de scaffolding e gerenciar o ciclo de vida do banco de dados:

• php volt make:controller — Geração automatizada de controladores desacoplados.
• php volt make:migration — Criação de arquivos de migração com timestamp nativo.
• php volt migrate — Execução sequencial das migrações pendentes.
• php volt rollback — Reversão do último lote de banco de dados.
• php volt make:context e make:context-total — Comandos customizados para geração de arquivos de contexto.

🧪 Qualidade de Código e Testes Integrados

Para garantir a estabilidade das aplicações residentes em memória, o Volt R² foi construído sob uma cultura de testes e tipagem estrita:

• Testes Automatizados (PHPUnit): Cobertura de testes unitários e de integração abrangendo o Container DI, Query Builder, Router, Rate Limiter e fluxo de Sessões.
• Análise Estática (PHPStan): Código-fonte totalmente validado e verificado na linha mais rígida do PHPStan (Level 9).