================================================================================ DOCUMENTAÇÃO DA ARQUITETURA E ESTRUTURA PROJETO BAGISTO ================================================================================ DATA DE CRIAÇÃO: 16 de Fevereiro de 2026 VERSÃO DO BAGISTO: 2.3.10 FRAMEWORK BASE: Laravel 11.0 LINGUAGEM: PHP 8.2+ FRONTEND: Vue.js, Vite ================================================================================ 1. VISÃO GERAL DO PROJETO ================================================================================ Bagisto é uma plataforma de e-commerce open-source construída sobre Laravel e Vue.js. O projeto utiliza uma arquitetura modular baseada em pacotes (packages), onde cada funcionalicdade é encapsulada em um módulo independente dentro do diretório packages/Webkul/. CARACTERÍSTICAS PRINCIPAIS: - Arquitetura modular baseada em pacotes - Separação entre Admin e Shop (loja frontend) - Sistema de multi-vendor (marketplace) - Suporte a múltiplos canais, moedas e idiomas - Sistema de atributos flexível para produtos - Gestão completa de pedidos, inventário e vendas - API RESTful para integrações - Sistema de temas customizáveis ================================================================================ 2. ESTRUTURA DE DIRETÓRIOS PRINCIPAL ================================================================================ bagisto/ │ ├── app/ # Aplicação principal Laravel │ ├── Http/ │ │ ├── Controllers/ # Controllers da aplicação │ │ └── Middleware/ # Middlewares customizados │ └── Providers/ # Service Providers da aplicação │ ├── bootstrap/ # Arquivos de inicialização │ ├── app.php # Configuração principal da aplicação │ └── providers.php # Lista de providers │ ├── config/ # Arquivos de configuração │ ├── app.php # Configurações gerais da aplicação │ ├── concord.php # Configuração dos módulos/pacotes │ ├── database.php # Configuração do banco de dados │ └── [outros arquivos de config] │ ├── database/ # Banco de dados │ ├── migrations/ # Migrations principais │ ├── seeders/ # Seeders do banco de dados │ └── factories/ # Factories para testes │ ├── packages/ # PACOTES MODULARES (Núcleo do Bagisto) │ └── Webkul/ # Namespace dos pacotes │ ├── Admin/ # Painel administrativo │ ├── Shop/ # Frontend da loja │ ├── Core/ # Funcionalidades core │ ├── Product/ # Gestão de produtos │ ├── Category/ # Gestão de categorias │ ├── Customer/ # Gestão de clientes │ ├── Sales/ # Gestão de vendas/pedidos │ ├── Checkout/ # Processo de checkout │ ├── CartRule/ # Regras de carrinho │ ├── CatalogRule/ # Regras de catálogo │ ├── Inventory/ # Gestão de inventário │ ├── Shipping/ # Métodos de envio │ ├── Payment/ # Métodos de pagamento │ ├── Tax/ # Gestão de impostos │ ├── Attribute/ # Sistema de atributos │ ├── CMS/ # Sistema de conteúdo │ ├── User/ # Gestão de usuários/admin │ ├── Theme/ # Sistema de temas │ ├── Marketing/ # Ferramentas de marketing │ ├── Notification/ # Sistema de notificações │ ├── SocialLogin/ # Login social │ ├── SocialShare/ # Compartilhamento social │ ├── BookingProduct/ # Produtos de reserva │ ├── DataGrid/ # Componente de grid de dados │ ├── DataTransfer/ # Importação/exportação │ ├── GDPR/ # Conformidade GDPR │ ├── FPC/ # Full Page Cache │ ├── Sitemap/ # Geração de sitemap │ ├── Paypal/ # Integração PayPal │ ├── Rule/ # Sistema de regras │ ├── MagicAI/ # Integração com IA │ ├── DebugBar/ # Barra de debug │ ├── Installer/ # Instalador do sistema │ └── Marketplace/ # Funcionalidades de marketplace │ ├── public/ # Arquivos públicos (web root) │ ├── index.php # Entry point da aplicação │ ├── storage/ # Link simbólico para storage │ └── [assets compilados] │ ├── resources/ # Recursos da aplicação │ ├── css/ # Arquivos CSS │ ├── js/ # Arquivos JavaScript │ └── views/ # Views Blade (se houver) │ ├── routes/ # Rotas da aplicação │ ├── web.php # Rotas web principais │ ├── console.php # Comandos console │ └── breadcrumbs.php # Breadcrumbs │ ├── storage/ # Arquivos de armazenamento │ ├── app/ # Arquivos da aplicação │ ├── framework/ # Cache e sessões │ └── logs/ # Logs da aplicação │ ├── tests/ # Testes automatizados │ ├── vendor/ # Dependências Composer (gerado) │ ├── composer.json # Dependências PHP ├── package.json # Dependências Node.js ├── vite.config.js # Configuração do Vite ├── .env.example # Exemplo de variáveis de ambiente └── README.md # Documentação do projeto ================================================================================ 3. ARQUITETURA MODULAR - ESTRUTURA DOS PACOTES ================================================================================ Cada pacote em packages/Webkul/ segue uma estrutura padronizada: [NomeDoPacote]/ │ ├── src/ # Código fonte do pacote │ ├── Config/ # Arquivos de configuração do pacote │ ├── Contracts/ # Interfaces/contratos │ ├── Console/ # Comandos Artisan │ ├── Database/ │ │ ├── Migrations/ # Migrations do pacote │ │ └── Factories/ # Factories para testes │ ├── Http/ │ │ ├── Controllers/ # Controllers do pacote │ │ ├── Middleware/ # Middlewares do pacote │ │ └── Requests/ # Form Requests (validação) │ ├── Models/ # Modelos Eloquent │ ├── Providers/ │ │ └── ModuleServiceProvider.php # Service Provider do módulo │ ├── Repositories/ # Repositórios (padrão Repository) │ ├── Resources/ │ │ ├── lang/ # Traduções │ │ ├── views/ # Views Blade │ │ └── manifest.php # Manifesto do pacote │ └── Routes/ # Rotas do pacote │ ├── web.php # Rotas web │ └── api.php # Rotas API (se aplicável) │ ├── tests/ # Testes do pacote └── composer.json # Configuração do pacote ================================================================================ 4. PACOTES PRINCIPAIS E SUAS RESPONSABILIDADES ================================================================================ 4.1. CORE (packages/Webkul/Core/) - Funcionalidades fundamentais do sistema - Gestão de canais (channels) - Gestão de moedas (currencies) - Gestão de localidades (locales) - Endereços e países - Configurações gerais - Classe Core.php (singleton principal) 4.2. ADMIN (packages/Webkul/Admin/) - Painel administrativo completo - Dashboard de gestão - Interface de administração - Rotas administrativas protegidas - Views e componentes admin 4.3. SHOP (packages/Webkul/Shop/) - Frontend da loja (storefront) - Interface do cliente - Rotas públicas da loja - Middlewares: Theme, Locale, Currency - Views e componentes da loja 4.4. PRODUCT (packages/Webkul/Product/) - Gestão completa de produtos - Tipos de produtos: simples, configurável, agrupado, bundle, virtual, downloadável - Atributos de produtos - Imagens e mídia - Preços e inventário - ProductFlat (tabela denormalizada para performance) 4.5. CATEGORY (packages/Webkul/Category/) - Gestão de categorias - Estrutura hierárquica (nested sets) - Categorias traduzíveis - Relacionamento com produtos 4.6. CUSTOMER (packages/Webkul/Customer/) - Gestão de clientes - Grupos de clientes - Endereços de clientes - Wishlist - Avaliações de produtos 4.7. SALES (packages/Webkul/Sales/) - Gestão de pedidos (orders) - Faturas (invoices) - Envios (shipments) - Reembolsos (refunds) - Transações de pagamento - Comentários de pedidos 4.8. CHECKOUT (packages/Webkul/Checkout/) - Processo de checkout - Gestão de carrinho (cart) - Endereços de entrega e cobrança - Métodos de envio e pagamento 4.9. ATTRIBUTE (packages/Webkul/Attribute/) - Sistema de atributos flexível - Famílias de atributos - Tipos de atributos: texto, select, multiselect, etc. - Atributos traduzíveis 4.10. INVENTORY (packages/Webkul/Inventory/) - Gestão de inventário - Fontes de inventário (inventory sources) - Controle de estoque - Reservas de produtos 4.11. SHIPPING (packages/Webkul/Shipping/) - Métodos de envio - Taxas de envio - Regras de envio por peso/destino 4.12. PAYMENT (packages/Webkul/Payment/) - Métodos de pagamento - Integrações com gateways - Processamento de pagamentos 4.13. TAX (packages/Webkul/Tax/) - Gestão de impostos - Categorias de impostos - Taxas de imposto - Mapeamento de impostos 4.14. CART RULE (packages/Webkul/CartRule/) - Regras de desconto no carrinho - Cupons de desconto - Condições e ações 4.15. CATALOG RULE (packages/Webkul/CatalogRule/) - Regras de preço no catálogo - Descontos automáticos - Condições baseadas em atributos 4.16. CMS (packages/Webkul/CMS/) - Gestão de conteúdo - Páginas estáticas - Blocos de conteúdo 4.17. USER (packages/Webkul/User/) - Gestão de usuários administrativos - Roles e permissões (Bouncer) - Autenticação admin 4.18. THEME (packages/Webkul/Theme/) - Sistema de temas - Customização de temas - Theme finder e renderização 4.19. MARKETPLACE (packages/Webkul/Marketplace/) - Funcionalidades multi-vendor - Gestão de vendedores (sellers) - Produtos de vendedores - Comissões e aprovações 4.20. MARKETING (packages/Webkul/Marketing/) - Ferramentas de marketing - Campanhas de email - Promoções 4.21. NOTIFICATION (packages/Webkul/Notification/) - Sistema de notificações - Notificações em tempo real - Templates de notificação 4.22. SOCIAL LOGIN (packages/Webkul/SocialLogin/) - Login com redes sociais - Integração com Laravel Socialite 4.23. BOOKING PRODUCT (packages/Webkul/BookingProduct/) - Produtos de reserva/agendamento - Disponibilidade - Calendários 4.24. DATA GRID (packages/Webkul/DataGrid/) - Componente de grid de dados - Tabelas interativas - Filtros e ordenação 4.25. DATA TRANSFER (packages/Webkul/DataTransfer/) - Importação/exportação de dados - CSV, Excel - Processamento em lote 4.26. GDPR (packages/Webkul/GDPR/) - Conformidade GDPR - Privacidade de dados - Consentimento 4.27. FPC (packages/Webkul/FPC/) - Full Page Cache - Cache de páginas completas - Performance 4.28. SITEMAP (packages/Webkul/Sitemap/) - Geração de sitemap XML - SEO 4.29. MAGIC AI (packages/Webkul/MagicAI/) - Integração com IA - OpenAI, GPT, etc. - Automação com IA 4.30. INSTALLER (packages/Webkul/Installer/) - Instalador do sistema - Setup inicial - Migrations e seeders ================================================================================ 5. SISTEMA DE ROTAS ================================================================================ 5.1. Rotas Principais (routes/web.php) - Rotas gerais da aplicação - Ponto de entrada principal 5.2. Rotas Admin (packages/Webkul/Admin/src/Routes/) - web.php # Rotas principais admin - auth-routes.php # Autenticação admin - catalog-routes.php # Gestão de catálogo - customers-routes.php # Gestão de clientes - sales-routes.php # Gestão de vendas - marketing-routes.php # Marketing - cms-routes.php # CMS - configuration-routes.php # Configurações - settings-routes.php # Configurações gerais - reporting-routes.php # Relatórios - notification-routes.php # Notificações - rest-routes.php # API REST admin 5.3. Rotas Shop (packages/Webkul/Shop/src/Routes/) - web.php # Rotas principais da loja - store-front-routes.php # Frontend da loja - customer-routes.php # Área do cliente - checkout-routes.php # Processo de checkout - api.php # API da loja 5.4. Rotas Marketplace (packages/Webkul/Marketplace/src/Routes/) - web.php # Rotas do marketplace - breadcrumbs.php # Breadcrumbs 5.5. Rotas Installer (packages/Webkul/Installer/src/Routes/) - web.php # Rotas do instalador ================================================================================ 6. MIDDLEWARES ================================================================================ 6.1. Middlewares Globais (bootstrap/app.php) - SecureHeaders # Headers de segurança - CanInstall # Verifica se pode instalar 6.2. Middlewares Shop (packages/Webkul/Shop/src/Http/Middleware/) - Theme # Aplica tema atual - Locale # Define locale/idioma - Currency # Define moeda atual - CacheResponse # Cache de respostas - AuthenticateCustomer # Autenticação de cliente 6.3. Middlewares Admin - Bouncer # Controle de acesso (roles/permissions) ================================================================================ 7. MODELOS E BANCO DE DADOS ================================================================================ 7.1. Estrutura de Models - Cada pacote possui seus próprios Models em src/Models/ - Models seguem padrão Eloquent do Laravel - Uso de Proxies para lazy loading (ex: ProductProxy) - Contracts (interfaces) em src/Contracts/ 7.2. Migrations - Migrations principais em database/migrations/ - Migrations de pacotes em packages/Webkul/[Pacote]/src/Database/Migrations/ - Total de ~226 migrations no sistema 7.3. Tabelas Principais - products # Produtos - product_flat # Produtos denormalizados (performance) - categories # Categorias - customers # Clientes - orders # Pedidos - order_items # Itens de pedidos - invoices # Faturas - shipments # Envios - carts # Carrinhos - cart_items # Itens do carrinho - attributes # Atributos - attribute_families # Famílias de atributos - channels # Canais - currencies # Moedas - locales # Idiomas - admins # Usuários admin - roles # Roles/permissões - marketplace_sellers # Vendedores (marketplace) - marketplace_products # Produtos de vendedores ================================================================================ 8. REPOSITÓRIOS (PADRÃO REPOSITORY) ================================================================================ Cada pacote utiliza o padrão Repository para abstrair acesso a dados: - Repositórios em src/Repositories/ - Interfaces em src/Contracts/ - Implementações em src/Repositories/ - Facilita testes e manutenção Exemplos: - ProductRepository - CategoryRepository - OrderRepository - CustomerRepository - etc. ================================================================================ 9. SERVICE PROVIDERS ================================================================================ 9.1. AppServiceProvider (app/Providers/AppServiceProvider.php) - Configurações gerais da aplicação - Debug bar condicional por IP 9.2. ModuleServiceProvider (em cada pacote) - Registra serviços do módulo - Carrega migrations, views, traduções - Registra rotas - Configura middlewares 9.3. Registro de Módulos (config/concord.php) - Lista todos os módulos ativos - Usa Konekt Concord para gerenciamento modular ================================================================================ 10. CONFIGURAÇÕES PRINCIPAIS ================================================================================ 10.1. Variáveis de Ambiente (.env) - APP_NAME # Nome da aplicação - APP_ENV # Ambiente (local/production) - APP_DEBUG # Modo debug - APP_URL # URL da aplicação - APP_ADMIN_URL # URL do admin (ex: admin) - DB_* # Configurações do banco - CACHE_STORE # Driver de cache - QUEUE_CONNECTION # Driver de filas - MAIL_* # Configurações de email - AWS_* # Configurações AWS (S3) 10.2. Configurações de Pacotes - Cada pacote pode ter arquivos em src/Config/ - Merge com config/ através do Service Provider ================================================================================ 11. FRONTEND E ASSETS ================================================================================ 11.1. Build System - Vite (vite.config.js) - Laravel Vite Plugin - Compilação de CSS e JS 11.2. Estrutura de Assets - resources/css/app.css # CSS principal - resources/js/app.js # JavaScript principal - Assets compilados em public/build/ 11.3. Views - Views Blade em packages/Webkul/[Pacote]/src/Resources/views/ - Namespace: admin:: ou shop:: - Componentes anônimos em Resources/views/components/ ================================================================================ 12. API E INTEGRAÇÕES ================================================================================ 12.1. API RESTful - Rotas API em packages/Webkul/Shop/src/Routes/api.php - Rotas API Admin em packages/Webkul/Admin/src/Routes/rest-routes.php - Autenticação via Laravel Sanctum 12.2. Integrações Externas - PayPal (packages/Webkul/Paypal/) - Social Login (packages/Webkul/SocialLogin/) - OpenAI/IA (packages/Webkul/MagicAI/) - Elasticsearch (para busca) ================================================================================ 13. SISTEMA DE TEMAS ================================================================================ 13.1. Estrutura de Temas - Temas em resources/themes/ - Cada tema tem sua própria estrutura - Sistema de herança de temas 13.2. Customização - ThemeCustomization model - Personalização via admin - CSS/JS customizados ================================================================================ 14. CACHE E PERFORMANCE ================================================================================ 14.1. Cache - Full Page Cache (FPC) - Response Cache (Spatie) - Cache de configurações - Cache de queries 14.2. Otimizações - ProductFlat (tabela denormalizada) - Índices de banco de dados - Lazy loading com Proxies - Eager loading quando necessário ================================================================================ 15. TESTES ================================================================================ 15.1. Estrutura de Testes - Testes em tests/ - Testes de pacotes em packages/Webkul/[Pacote]/tests/ - Framework: Pest PHP (com PHPUnit) 15.2. Factories - Factories em database/factories/ - Factories de pacotes em packages/Webkul/[Pacote]/src/Database/Factories/ ================================================================================ 16. DEPENDÊNCIAS PRINCIPAIS ================================================================================ 16.1. PHP (composer.json) - Laravel Framework ^11.0 - Laravel Sanctum ^4.0 - Laravel Socialite ^5.0 - Intervention Image ^2.4 - Konekt Concord ^1.2 (modularidade) - Spatie ResponseCache ^7.4 - Maatwebsite Excel ^3.1.46 - Elasticsearch ^8.10 - OpenAI PHP Laravel ^0.10.1 - E muitas outras... 16.2. JavaScript (package.json) - Vite ^5.4.12 - Laravel Vite Plugin ^1.0 - Axios ^1.7.9 ================================================================================ 17. FLUXO DE REQUISIÇÃO ================================================================================ 1. Requisição HTTP → public/index.php 2. Bootstrap → bootstrap/app.php 3. Service Providers registrados 4. Middlewares aplicados: - Globais (SecureHeaders, CanInstall) - Web group (sessão, CSRF, etc.) - Shop group (Theme, Locale, Currency) OU Admin 5. Roteamento → Routes do pacote apropriado 6. Controller → Processa requisição 7. Repository → Acessa dados 8. Model → Interage com banco 9. View → Renderiza resposta 10. Response → Retorna ao cliente ================================================================================ 18. MULTI-TENANCY E MULTI-CHANNEL ================================================================================ 18.1. Canais (Channels) - Cada loja pode ter múltiplos canais - Cada canal tem suas próprias configurações - Produtos podem estar em múltiplos canais 18.2. Locales e Moedas - Suporte a múltiplos idiomas - Suporte a múltiplas moedas - Taxas de câmbio configuráveis ================================================================================ 19. MARKETPLACE (MULTI-VENDOR) ================================================================================ 19.1. Funcionalidades - Gestão de vendedores (sellers) - Produtos por vendedor - Comissões configuráveis - Aprovação de produtos - Dashboard do vendedor 19.2. Estrutura - Pacote Marketplace em packages/Webkul/Marketplace/ - Tabelas: marketplace_sellers, marketplace_products - Rotas e controllers específicos ================================================================================ 20. SEGURANÇA ================================================================================ 20.1. Autenticação - Admin: Laravel Auth + Bouncer (roles) - Customer: Laravel Auth - API: Laravel Sanctum 20.2. Proteções - CSRF Protection - XSS Protection - SQL Injection (Eloquent ORM) - Secure Headers middleware - Password hashing (bcrypt) ================================================================================ 21. INTERNACIONALIZAÇÃO (i18n) ================================================================================ 21.1. Traduções - Arquivos em packages/Webkul/[Pacote]/src/Resources/lang/ - Suporte a múltiplos idiomas - Laravel Translatable para modelos 21.2. Locales Suportados - Inglês, Português, Espanhol, Alemão, Francês, etc. - Configurável por canal ================================================================================ 22. COMANDOS ARTISAN ================================================================================ 22.1. Comandos Principais - php artisan bagisto:install # Instalação - php artisan bagisto:version # Versão - php artisan bagisto:upgrade # Upgrade - php artisan bagisto:publish # Publicar assets 22.2. Comandos de Pacotes - Cada pacote pode ter comandos em src/Console/Commands/ ================================================================================ 23. LOGS E DEBUG ================================================================================ 23.1. Logs - storage/logs/laravel.log - Logs por canal (se configurado) 23.2. Debug - DebugBar (desenvolvimento) - APP_DEBUG no .env - APP_DEBUG_ALLOWED_IPS para produção ================================================================================ 24. ARQUIVOS E STORAGE ================================================================================ 24.1. Storage - storage/app/ # Arquivos da aplicação - storage/app/public/ # Arquivos públicos - storage/framework/ # Cache, sessões, views - storage/logs/ # Logs 24.2. Uploads - Produtos: storage/app/public/products/ - Categorias: storage/app/public/categories/ - CMS: storage/app/public/cms/ - Avatares: storage/app/public/customers/ ================================================================================ 25. PERSONALIZAÇÃO E EXTENSIBILIDADE ================================================================================ 25.1. Criar Novo Pacote - Criar estrutura em packages/Webkul/[NovoPacote]/ - Seguir estrutura padrão - Registrar em config/concord.php - Criar ModuleServiceProvider 25.2. Override de Pacotes - Usar Service Providers - Binding de interfaces - Extensão de classes 25.3. Temas Customizados - Criar em resources/themes/ - Herdar de tema base - Customizar views e assets ================================================================================ 26. DEPLOY E PRODUÇÃO ================================================================================ 26.1. Preparação - composer install --optimize-autoloader --no-dev - npm run build - php artisan config:cache - php artisan route:cache - php artisan view:cache - php artisan optimize 26.2. Variáveis de Ambiente - APP_ENV=production - APP_DEBUG=false - Configurar banco de dados - Configurar cache (Redis recomendado) - Configurar filas 26.3. Permissões - storage/ e bootstrap/cache/ devem ser graváveis ================================================================================ 27. VERSIONAMENTO ================================================================================ - Versão atual: 2.3.10 - Versão definida em packages/Webkul/Core/src/Core.php - Sistema de upgrade via comandos Artisan ================================================================================ 28. COMUNIDADE E SUPORTE ================================================================================ - GitHub: https://github.com/bagisto/bagisto - Documentação: https://devdocs.bagisto.com/ - Fóruns: https://forums.bagisto.com/ - Facebook Group: https://www.facebook.com/groups/bagisto ================================================================================ 29. LICENÇA ================================================================================ MIT License - Open Source ================================================================================ 30. CONCLUSÃO ================================================================================ O Bagisto é uma plataforma de e-commerce robusta e modular construída sobre Laravel 11. Sua arquitetura baseada em pacotes permite extensibilidade e manutenção facilitada. Cada funcionalidade é encapsulada em seu próprio módulo, seguindo padrões de design como Repository Pattern, Service Providers e Contracts. A separação clara entre Admin e Shop, junto com o sistema de temas e internacionalização, torna o Bagisto uma solução flexível para diversos tipos de negócios de e-commerce, desde lojas simples até marketplaces multi-vendor complexos. ================================================================================ FIM DA DOCUMENTAÇÃO ================================================================================