How heliomatos-tech/site-agrupei works
1. This is a Laravel monolith for a multi-sided marketplace. The main runtime is a single PHP/Laravel application, backed by a relational database, filesystem storage under storage/app/public, queued jobs, and standard Laravel web/API routing.
2. The codebase is intentionally layered. Most business capabilities follow the same flow: HTTP controller → validation class → application service → repository → Eloquent model/database. Interfaces are defined alongside concrete implementations and are bound through feature-specific service providers in app/Providers.
3. The app is split by user/tenant-facing surface:
- public/consumer web UI
- seller portal (selleradm)
- admin back office
- JSON API under routes/api.php
- special webhook endpoints for payments and notifications
This separation is reflected in both controllers and route files.
4. The core domain revolves around commerce objects: offers, products, categories, cart, orders, payments, vouchers, coupons, cashback, ratings, comments, and favorites. These modules have dedicated repositories/services and frequently use transaction services for write workflows that span multiple tables.
5. There is a strong seller/consumer identity boundary. Separate feature groups exist for Consumer, Seller, SellerUser, ConsumerAddress, SellerAddress, ConsumerPaymentMethod, AuthSellerUser, AuthAdminUser, and related role/status workflows. Middleware like AuthConsumerUser, AuthSellerUser, AuthAdminUser, EnsureSellerUserRole, and route-hash guards enforce those boundaries.
6. Admin operations are a major subsystem, not an afterthought. The app/Features/Admin/* tree covers audit, campaigns, content, coupons, discounts, mediation, notifications, order payments, reports, settings, team management, profile, and dashboard metrics. These admin features typically read/write the same core tables but through separate services and web controllers.
7. Commerce fulfillment spans several chained subsystems:
- offer/product creation and moderation
- cart and checkout
- order creation and order items
- payment creation/pay execution
- voucher generation/verification/use
- shipping quote calculation
The most transaction-heavy paths are order creation, payment creation, and product/offer updates, each with paired transaction services.
8. Payment integration is abstracted behind a gateway layer. PaymentGateway contains a factory plus gateway-specific services, including PagBank and legacy adapters, while Payment feature services handle validation and processing logic. API/webhook controllers capture payment events and update order/payment state.
9. Notifications are also modularized. Notification and AdminNotifications cover templates, dispatches, email open tracking, webhooks, logs, and send jobs. The asynchronous part is handled by queued jobs in app/Jobs/Notification, with channels for email/SMS/WhatsApp and a channel factory.
10. Location and catalog enrichment are first-class cross-cutting services. Separate features exist for Brazilian states/cities, geocoding, seller location, consumer location filtering, and offer enrichment by city name. These services are used by offer discovery, signup/profile flows, and seller address forms.
11. Content and marketing features are domain modules on their own: announcements, announcement/content highlights, pages, menu options, banners/icons/tags/sessions, campaigns, coupons, discount rules, featured packages, and homepage sections. These modules power both admin management screens and public display components.
12. The repository has substantial support tooling baked in:
- Artisan commands for backfills, reconciliation, code generation, and maintenance
- custom validators and DTOs
- helper classes for formatting, SEO, response shaping, QR codes, hashing, and notifications
- custom casts like encrypted card number handling
This indicates a mature codebase with a lot of domain-specific infrastructure beyond vanilla Laravel.
13. Persistence is centered on Eloquent models and migrations. The schema includes many domain tables for users, sellers, offers, orders, payments, content, mediation, notifications, and admin settings. Seeders and a checked-in schema dump suggest the project is designed to be reproducibly bootstrapped and populated in different environments.
14. Front-end delivery is server-rendered Blade views, not a SPA. Views are organized by role and domain, with shared components and partials, plus JavaScript helpers for validation, masking, file previews, dialogs, and input behavior. Public assets and uploaded media are served from public/ and the Laravel public storage symlink.
15. Tests are organized around critical business paths rather than only unit boundaries. There are feature tests for checkout, offers, user creation with address/geocoding, admin dashboards, coupon serialization, offer images, and voucher lifecycle, plus unit tests for dashboard services and JS handlers. This reinforces that the key architecture is behavior-driven around workflows.
Main entry points: Models Models & schema · Web Web controllers · Providers Providers · Cart Cart & checkout
Components 20
Delivery
HTTP entrypoints, routes, and Blade rendering
- Web routes · Public, seller, consumer, and admin web route files that bind pages to controllers
routes/web.php - API routes · JSON APIs, auth endpoints, and webhooks
routes/api.php - Web controllers · Server-rendered controllers for public, consumer, seller, and admin views
app/Http/Controllers/Web - API controllers · JSON controllers for mobile/web integrations and webhook callbacks
app/Http/Controllers/Api - Blade views · Role-scoped server-rendered views and shared partials
resources/views
Commerce
Core marketplace workflows and fulfillment
- Catalog · Offers, products, categories, images, features, and enrichment flows
app/Features/Offer - Cart & checkout · Cart management, checkout orchestration, order creation, and order items
app/Features/Cart - Payments · Payment processing and gateway abstraction for create/pay flows
app/Features/Payment - Vouchers · Voucher listing, formatting, verification, and use in purchase flows
app/Features/Voucher - Engagement · Comments, ratings, favorites, coupons, cashback, announcements, highlights, campaigns, and pages
app/Features/OfferComment
Admin
Back-office operations and dashboards
- Admin dashboard · Dashboard metrics, alerts, KPIs, and performance views
app/Features/Dashboard - Admin ops · Audit, campaigns, content, coupons, discounts, mediation, notifications, order payments, reports, settings, team, and profile
app/Features/Admin
Identity
Role-aware authentication and profile boundaries
- Middleware · Route-hash, auth, role, and request-shaping middleware
app/Http/Middleware - Auth flows · Login, logout, and guard-specific auth services for consumers, sellers, and admins
app/Features/Auth - User sides · Consumer, seller, seller-user, address, and payment-method boundaries
app/Features/Consumer
Infrastructure
Persistence, async work, storage, and shared services
- Location · Brazilian states/cities, geocoding, seller location, and offer filtering by city
app/Features/City - Notifications · Template-driven notifications, email open tracking, webhook handling, and send jobs
app/Features/Notification - Models & schema · Eloquent models, migrations, seeders, and schema dump for the relational data layer
app/Models - Providers · Feature service providers that bind interfaces to implementations
app/Providers - Jobs & tools · Queued jobs, artisan commands, helper libraries, casts, and operational utilities
app/Jobs
Connections 23
- Web routes → Web controllers: dispatches to · Web route files map role-specific pages to controllers
- API routes → API controllers: dispatches to · API route files map JSON endpoints and webhooks to controllers
- Web controllers → Blade views: renders · Controllers return Blade views and partials
- Web controllers → Middleware: protected by · Role and route-hash middleware gate access to web areas
- API controllers → Middleware: protected by · API and webhook endpoints use auth and request guards
- Web controllers → Providers: resolved via · Controllers rely on provider-bound feature services
- API controllers → Providers: resolved via · API controllers use the same provider-bound services
- Auth flows → Middleware: enforced by · Authentication features pair with guard middleware for consumer, seller, and admin boundaries
- User sides → Auth flows: uses · Identity and profile flows depend on guard-specific auth services
- User sides → Location: uses · Address and signup flows use geocoding and city resolution
- Catalog → Location: enriched by · Offer discovery can be filtered or labeled by city
- Cart & checkout → Catalog: consumes · Cart and checkout start from offers and product data
- Cart & checkout → Payments: creates payment · Checkout hands off to payment creation and pay execution
- Cart & checkout → Vouchers: emits · Order completion drives voucher generation and usage lifecycle
- Payments → Notifications: notifies · Payment events can trigger webhook-driven notifications and status updates
- Vouchers → Models & schema: stores in · Voucher state is persisted through Eloquent models and tables
- Engagement → Models & schema: stores in · Content, moderation, and engagement modules persist to relational tables
- Admin dashboard → Models & schema: queries · Dashboard metrics and performance views aggregate core tables
- Admin ops → Providers: resolved via · Admin feature trees are bound through dedicated service providers
- Admin ops → Models & schema: reads and writes · Admin workflows operate on the same underlying domain tables
- Notifications → Jobs & tools: async work · Notification dispatching and sends are handled by queued jobs
- Jobs & tools → Models & schema: maintains · Commands, backfills, and utility services support data and storage consistency
- Providers → Models & schema: binds to · Feature providers connect repository and service abstractions to model-backed implementations