How joaobortolotti/guiativa works
1. What this repository is
- A monolithic Laravel application called Guiativa.
- It is a server-rendered app using Blade views for UI, with PHP/Laravel as the backend and Vite/Tailwind/vanilla JS for front-end assets.
- The product domain is a local commerce directory / agenda: consumers browse stores, promotions, contacts, hours, and locations; merchants manage their listing and plan status.
2. Request entry and application bootstrap
- HTTP traffic enters through public/index.php, then Laravel boots via bootstrap/app.php.
- Application structure is the standard Laravel layered flow: routes → middleware → controllers → form requests → models → database → Blade responses.
- The repo includes separate route files for web, auth, api, channels, and console, so web pages, authentication, and ancillary endpoints are intentionally separated.
3. Main user-facing surfaces
- resources/views/welcome.blade.php is the landing page and appears to support search by commerce and city plus category-style navigation.
- resources/views/announcement.blade.php and resources/views/announcement/info.blade.php represent the public listing/detail experience for a commerce announcement.
- resources/views/dashboard.blade.php, resources/views/profile/*, and resources/views/plano/* are the logged-in merchant/account areas.
- resources/views/auth/* covers the standard authentication journey.
4. Core domain subsystems
- The main business entities are modeled in app/Models:
- Anuncio for the store/listing/announcement
- Endereco for address data
- Contato for contact details
- Horario_comercial for opening hours
- Plano for subscription/plan state
- CEP for postal-code-driven address lookup or normalization
- User for account identity
- This suggests the app centers on a merchant profile composed of several related records, not a single flat table.
5. Announcement management workflow
- app/Http/Controllers/AnuncioController.php handles the listing lifecycle.
- app/Http/Requests/Anuncio/StoreAnuncioRequest.php indicates create/update validation is separated from controller logic.
- Merchant-facing forms in resources/views/profile/partials/update-anuncio-information-form.blade.php and related partials suggest the merchant profile page is decomposed into sections for each domain area.
- Public images for announcements live under public/img/events, implying uploaded/served storefront imagery is a key part of the listing model.
6. Merchant account/profile subsystem
- ProfileController and app/Http/Requests/ProfileUpdateRequest.php manage account/profile edits.
- The profile page is split into partial forms for:
- profile identity
- password
- delete user
- announcement info
- contact info
- address info
- business hours
- This is a strong indicator that the account screen is the central control panel for merchants to keep their commerce listing current.
7. Plan and payment-related flow
- PlanoController and resources/views/plano/{contrato,editar,pagar}.blade.php define a dedicated plan/subscription area.
- The README says merchants can verify the status of the plan, so plan state is likely tied to account eligibility or visibility.
- The architecture appears to keep plan management separate from general profile editing, which is an important boundary in any diagram.
8. Location, address, and contact enrichment
- resources/js/cep.js and the CEP model indicate postal-code lookup or address autofill.
- resources/js/maps.js suggests map rendering or geolocation support for business location display.
- The EnderecoController and ContatoController handle structured commerce contact/location data, likely feeding both merchant edit screens and public listing pages.
9. Authentication and security boundaries
- Auth is implemented with dedicated controllers under app/Http/Controllers/Auth, including login, registration, password reset, email verification, and password confirmation.
- Middleware in app/Http/Middleware includes:
- Authenticate, RedirectIfAuthenticated
- VerifyCsrfToken
- TrimStrings
- EncryptCookies
- PreventRequestsDuringMaintenance
- HttpsProtocol for forcing HTTPS
- This means the app has a conventional Laravel security boundary with authenticated merchant-only sections and CSRF-protected forms.
10. Frontend composition
- UI is built from Blade layouts and reusable components in resources/views/components and app/View/Components.
- Layouts include app, guest, navigation, and bottom_bar, so the public site and authenticated area have distinct shells.
- Client-side assets in resources/js also include estrelas.js and imagem.js, suggesting small interactive behaviors around rating/display and image handling.
11. Persistence and schema
- The database layer is migration-driven via database/migrations, with tables for users, announcements, contacts, addresses, CEPs, opening hours, plans, and standard Laravel auth tables.
- database/factories/UserFactory.php and database/seeders/DatabaseSeeder.php support test/data bootstrapping.
- Because the domain tables are split by concern, the diagram should show the data model as a set of related business records rather than one monolithic listing table.
12. Infrastructure and operational details
- docker-compose.yml suggests the project is intended to run in a containerized local/dev environment.
- storage/ and bootstrap/cache/ are standard Laravel runtime areas for logs, cached config/views, sessions, and generated files.
- public/ hosts static assets and publicly served uploaded content.
13. Localization and presentation
- The application is localized in Portuguese (pt_BR) with custom translation files under lang/pt_BR.
- This matters because the UI, validation messages, and auth flows are likely all branded and worded for Brazilian users.
- Any architecture diagram should reflect a Brazilian commerce directory with CEP/address and local-business semantics.
14. What to emphasize in an architecture diagram
- Draw the system as a single Laravel monolith with three major zones:
- Public discovery: welcome page, announcement listing/detail, search/navigation
- Merchant management: dashboard/profile/plan/edit forms
- Platform services: authentication, validation, persistence, static assets, localization
- Show the primary flow as: browser → Laravel routes/middleware → controllers/form requests → Eloquent models/database → Blade views/static assets.
Main entry points: web.php Public routes · Anuncio.php Models · AnuncioController.php Anuncio controller · edit.blade.php Profile editor
Components 20
Public discovery
Unauthenticated browsing and public listing pages for local commerce discovery.
- Public routes · Web entry points for landing, announcements, and general browsing.
routes/web.php - Welcome page · Landing page with search and category-style navigation.
resources/views/welcome.blade.php - Announcement pages · Listing and detail views for commerce announcements.
resources/views/announcement.blade.php - Anuncio controller · Handles announcement lifecycle and public listing interactions.
app/Http/Controllers/AnuncioController.php - Listing validation · Validates announcement create and update data.
app/Http/Requests/Anuncio/StoreAnuncioRequest.php
Merchant management
Authenticated dashboard, profile, and plan workflows for listing owners.
- Merchant dashboard · Central merchant area for account and commerce management.
resources/views/dashboard.blade.php - Profile editor · Profile screen and partial forms for merchant account and listing details.
resources/views/profile/edit.blade.php - Profile controller · Updates account and merchant profile data.
app/Http/Controllers/ProfileController.php - Profile validation · Validates merchant profile updates.
app/Http/Requests/ProfileUpdateRequest.php - Plan area · Merchant plan pages for contract, edit, and payment flows.
resources/views/plano/contrato.blade.php - Plan controller · Manages subscription state and plan-related actions.
app/Http/Controllers/PlanoController.php
Platform services
Cross-cutting Laravel runtime concerns: routing, auth, validation, middleware, and shared UI.
- Auth stack · Login, registration, reset, verification, and password confirmation flows.
routes/auth.php - HTTP middleware · CSRF, auth, redirects, HTTPS enforcement, and request hygiene.
app/Http/Kernel.php - Laravel bootstrap · Bootstraps the application and wires core services.
bootstrap/app.php - Layouts and components · Shared Blade layouts and reusable UI components.
resources/views/layouts/app.blade.php
Data and assets
Persistence, seeded data, translations, and served frontend/static resources.
- Models · Eloquent models for listings, contacts, addresses, hours, plans, CEP, and users.
app/Models/Anuncio.php - Database schema · Migration-driven tables for users, announcements, contacts, addresses, CEPs, hours, and plans.
database/migrations/2023_05_16_211704_create_anuncios_table.php - Assets and static · Vite-built JavaScript/CSS, maps, CEP autofill, images, and public files.
resources/js/app.js - Localization · Portuguese Brazilian validation, auth, and UI strings.
lang/pt_BR.json
Other components
- Browser · End users and merchants access the app through HTTP.
Connections 28
- Browser → Public routes: requests · Browser traffic enters the web routes.
- Public routes → Welcome page: renders · Public route serves the landing page.
- Public routes → Announcement pages: renders · Public route serves announcement pages.
- Public routes → Anuncio controller: dispatches · Routes forward listing actions to the announcement controller.
- Anuncio controller → Listing validation: validates · Announcement input is validated before persistence.
- Anuncio controller → Models: persists · Listing controller reads and writes announcement data.
- Anuncio controller → Announcement pages: returns · Controller returns public announcement views.
- Browser → Auth stack: authenticates · Login, registration, and recovery flows are handled separately.
- Auth stack → HTTP middleware: protected by · Authentication endpoints are guarded by middleware and request checks.
- Browser → Merchant dashboard: opens · Authenticated merchants land in the dashboard.
- Merchant dashboard → Profile editor: links to · Dashboard exposes profile management.
- Profile editor → Profile controller: updates via · Profile form submits to the profile controller.
- Profile controller → Profile validation: validates · Profile updates use a dedicated request object.
- Profile controller → Models: updates · Profile controller writes merchant and listing-related models.
- Profile editor → Plan area: links to · Profile area surfaces plan management.
- Plan area → Plan controller: handled by · Plan pages are coordinated by the plan controller.
- Plan controller → Models: reads · Plan state is tied back to domain records.
- Laravel bootstrap → HTTP middleware: loads · Bootstrap initializes the HTTP middleware stack.
- HTTP middleware → Public routes: protects · Middleware wraps the web route surface.
- HTTP middleware → Auth stack: protects · Middleware also guards auth endpoints.
- Public routes → Layouts and components: uses · Web pages are composed from shared Blade layouts and components.
- Profile editor → Layouts and components: uses · Merchant forms reuse the same Blade shell and components.
- Models → Database schema: stored in · Eloquent models map to migration-defined tables.
- Assets and static → Welcome page: enhances · Frontend assets support search, maps, images, and small interactions.
- Assets and static → Announcement pages: enhances · Static assets enrich public listing presentation.
- Localization → Welcome page: localizes · UI strings and validation copy are localized in pt_BR.
- Localization → Auth stack: localizes · Authentication flows use Portuguese translation files.
- Models → Localization: consumes · Model and form messages are presented in the localized UI.