# heliomatos-tech/site-agrupei architecture

> Architecture diagram of the GitHub repository heliomatos-tech/site-agrupei, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/heliomatos-tech/site-agrupei
- Repository: https://github.com/heliomatos-tech/site-agrupei

## Overview

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: [`app/Models`](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Models) (Models & schema), [`app/Http/Controllers/Web`](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Http/Controllers/Web) (Web controllers), [`app/Providers`](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Providers) (Providers), [`app/Features/Cart`](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Cart) (Cart & checkout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_delivery["Delivery"]
  node_web_routes["Web routes<br/>route entrypoints<br/>[web.php]"]
  node_api_routes["API routes<br/>route entrypoints<br/>[api.php]"]
  node_web_controllers["Web controllers<br/>HTTP controllers"]
  node_api_controllers["API controllers<br/>HTTP controllers"]
  node_blade_views["Blade views<br/>presentation layer"]
end

subgraph group_commerce["Commerce"]
  node_offer_catalog["Catalog<br/>commerce domain"]
  node_cart_checkout["Cart & checkout<br/>commerce workflow"]
  node_payments_gateway["Payments<br/>payment workflow"]
  node_voucher_fulfillment["Vouchers<br/>fulfillment feature"]
  node_engagement_modules["Engagement<br/>domain modules"]
end

subgraph group_admin["Admin"]
  node_admin_dashboard["Admin dashboard<br/>admin analytics"]
  node_admin_ops["Admin ops<br/>admin features"]
end

subgraph group_identity["Identity"]
  node_middleware{{"Middleware<br/>request guards"}}
  node_auth_features["Auth flows<br/>identity features"]
  node_consumer_seller_core["User sides<br/>identity features"]
end

subgraph group_infrastructure["Infrastructure"]
  node_location_services["Location<br/>cross-cutting service"]
  node_notifications["Notifications<br/>async messaging"]
  node_persistence_models[("Models & schema<br/>persistence")]
  node_service_providers{{"Providers<br/>bindings"}}
  node_jobs_storage_tools["Jobs & tools<br/>async and tooling"]
end

node_web_routes -->|"dispatches to"| node_web_controllers
node_api_routes -->|"dispatches to"| node_api_controllers
node_web_controllers -->|"renders"| node_blade_views
node_web_controllers -.->|"protected by"| node_middleware
node_api_controllers -.->|"protected by"| node_middleware
node_web_controllers -.->|"resolved via"| node_service_providers
node_api_controllers -.->|"resolved via"| node_service_providers
node_auth_features -->|"enforced by"| node_middleware
node_consumer_seller_core -->|"uses"| node_auth_features
node_consumer_seller_core -.->|"uses"| node_location_services
node_offer_catalog -.->|"enriched by"| node_location_services
node_cart_checkout -->|"consumes"| node_offer_catalog
node_cart_checkout -->|"creates payment"| node_payments_gateway
node_cart_checkout -.->|"emits"| node_voucher_fulfillment
node_payments_gateway -.->|"notifies"| node_notifications
node_voucher_fulfillment -->|"stores in"| node_persistence_models
node_engagement_modules -->|"stores in"| node_persistence_models
node_admin_dashboard -->|"queries"| node_persistence_models
node_admin_ops -.->|"resolved via"| node_service_providers
node_admin_ops -->|"reads and writes"| node_persistence_models
node_notifications -->|"async work"| node_jobs_storage_tools
node_jobs_storage_tools -.->|"maintains"| node_persistence_models
node_service_providers -.->|"binds to"| node_persistence_models

click node_web_routes "https://github.com/heliomatos-tech/site-agrupei/blob/main/routes/web.php"
click node_api_routes "https://github.com/heliomatos-tech/site-agrupei/blob/main/routes/api.php"
click node_web_controllers "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Http/Controllers/Web"
click node_api_controllers "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Http/Controllers/Api"
click node_blade_views "https://github.com/heliomatos-tech/site-agrupei/tree/main/resources/views"
click node_middleware "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Http/Middleware"
click node_auth_features "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Auth"
click node_consumer_seller_core "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Consumer"
click node_offer_catalog "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Offer"
click node_cart_checkout "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Cart"
click node_payments_gateway "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Payment"
click node_voucher_fulfillment "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Voucher"
click node_engagement_modules "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/OfferComment"
click node_location_services "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/City"
click node_admin_dashboard "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Dashboard"
click node_admin_ops "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Admin"
click node_notifications "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Notification"
click node_persistence_models "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Models"
click node_service_providers "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Providers"
click node_jobs_storage_tools "https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Jobs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web_routes,node_api_routes,node_web_controllers,node_api_controllers,node_blade_views toneBlue
class node_offer_catalog,node_cart_checkout,node_payments_gateway,node_voucher_fulfillment,node_engagement_modules toneAmber
class node_admin_dashboard,node_admin_ops toneMint
class node_middleware,node_auth_features,node_consumer_seller_core toneRose
class node_location_services,node_notifications,node_persistence_models,node_service_providers,node_jobs_storage_tools toneIndigo
```

## Components

### Delivery

HTTP entrypoints, routes, and Blade rendering

- [Web routes](https://github.com/heliomatos-tech/site-agrupei/blob/main/routes/web.php): route entrypoints · Public, seller, consumer, and admin web route files that bind pages to controllers · `routes/web.php`
- [API routes](https://github.com/heliomatos-tech/site-agrupei/blob/main/routes/api.php): route entrypoints · JSON APIs, auth endpoints, and webhooks · `routes/api.php`
- [Web controllers](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Http/Controllers/Web): HTTP controllers · Server-rendered controllers for public, consumer, seller, and admin views · `app/Http/Controllers/Web`
- [API controllers](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Http/Controllers/Api): HTTP controllers · JSON controllers for mobile/web integrations and webhook callbacks · `app/Http/Controllers/Api`
- [Blade views](https://github.com/heliomatos-tech/site-agrupei/tree/main/resources/views): presentation layer · Role-scoped server-rendered views and shared partials · `resources/views`

### Commerce

Core marketplace workflows and fulfillment

- [Catalog](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Offer): commerce domain · Offers, products, categories, images, features, and enrichment flows · `app/Features/Offer`
- [Cart & checkout](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Cart): commerce workflow · Cart management, checkout orchestration, order creation, and order items · `app/Features/Cart`
- [Payments](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Payment): payment workflow · Payment processing and gateway abstraction for create/pay flows · `app/Features/Payment`
- [Vouchers](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Voucher): fulfillment feature · Voucher listing, formatting, verification, and use in purchase flows · `app/Features/Voucher`
- [Engagement](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/OfferComment): domain modules · Comments, ratings, favorites, coupons, cashback, announcements, highlights, campaigns, and pages · `app/Features/OfferComment`

### Admin

Back-office operations and dashboards

- [Admin dashboard](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Dashboard): admin analytics · Dashboard metrics, alerts, KPIs, and performance views · `app/Features/Dashboard`
- [Admin ops](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Admin): admin features · 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](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Http/Middleware): request guards · Route-hash, auth, role, and request-shaping middleware · `app/Http/Middleware`
- [Auth flows](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Auth): identity features · Login, logout, and guard-specific auth services for consumers, sellers, and admins · `app/Features/Auth`
- [User sides](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Consumer): identity features · Consumer, seller, seller-user, address, and payment-method boundaries · `app/Features/Consumer`

### Infrastructure

Persistence, async work, storage, and shared services

- [Location](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/City): cross-cutting service · Brazilian states/cities, geocoding, seller location, and offer filtering by city · `app/Features/City`
- [Notifications](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Features/Notification): async messaging · Template-driven notifications, email open tracking, webhook handling, and send jobs · `app/Features/Notification`
- [Models & schema](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Models): persistence · Eloquent models, migrations, seeders, and schema dump for the relational data layer · `app/Models`
- [Providers](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Providers): bindings · Feature service providers that bind interfaces to implementations · `app/Providers`
- [Jobs & tools](https://github.com/heliomatos-tech/site-agrupei/tree/main/app/Jobs): async and tooling · Queued jobs, artisan commands, helper libraries, casts, and operational utilities · `app/Jobs`

## Connections

- 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
