3. Laravel + React Structure (stoqio)

This structure is aligned with the current stoqio codebase in this repository, not older legacy project layouts.

Backend (Laravel) Structure

stoqio/
|-- app/
|   |-- Console/
|   |-- Constant/
|   |-- Contracts/
|   |-- Data/
|   |-- Enums/
|   |-- Exceptions/
|   |-- Factory/
|   |-- Gateways/
|   |-- Helpers/
|   |-- Http/
|   |   |-- Controllers/
|   |   |   `-- Api/
|   |   |       `-- Backoffice/
|   |   |-- Middleware/
|   |   `-- Requests/
|   |-- Jobs/
|   |-- Mail/
|   |-- Models/
|   |-- Notifications/
|   |-- Providers/
|   |-- Sections/
|   |-- Services/
|   |-- Swagger/
|   |-- Traits/
|   `-- Utils/
|-- bootstrap/
|-- config/
|-- database/
|   |-- migrations/
|   |-- seeders/
|   `-- sql/
|-- public/
|-- resources/
|   |-- views/
|   |   |-- components/
|   |   |-- frontend/
|   |   |-- installer/
|   |   |-- mails/
|   |   `-- pdf/
|   `-- lang/
|-- routes/
|   |-- api.php
|   |-- web.php
|   |-- installer.php
|   |-- channels.php
|   `-- console.php
`-- storage/

Route Organization (Actual)

• routes/api.php: all API routes under /api/v1 (public, protected, backoffice).
• routes/web.php: website/web routes.
• routes/installer.php: installation and setup flow routes.
• routes/channels.php: broadcast channel authorization.
• routes/console.php: scheduled/console route definitions.

Key Backend Layers

Controllers

• app/Http/Controllers/Api: main API module controllers (inventory, invoice, stock, report, settings).
• app/Http/Controllers/Api/Backoffice: backoffice-only APIs (companies, plans, languages, content, gateways).

Services

• app/Services/Api: business logic layer for API modules.
• Keep controllers thin; move validation/result orchestration logic to service classes.

Models

• app/Models: database entities for product, inventory, invoices, transfers, returns, users, etc.
• Scope by company_id where applicable for tenant safety.

Requests and Middleware

• app/Http/Requests: request validation classes.
• app/Http/Middleware: guards including auth:api, throttle, and feature-access controls.

Frontend (React - frontend-source) Structure

frontend-source/
|-- public/
|-- src/
|   |-- api/         # API clients and request methods
|   |-- assets/      # Static assets
|   |-- components/  # Reusable UI components
|   |-- config/      # Constants, endpoint base configs
|   |-- context/     # Global contexts
|   |-- hooks/       # Custom hooks
|   |-- layout/      # App layout wrappers
|   |-- locales/     # i18n resources
|   |-- pages/       # Module pages (product, stock, invoice, report, backoffice)
|   |-- routes/      # Route map + guards
|   |-- slice/       # Redux slices
|   |-- store/       # Redux store setup
|   `-- utils/       # Helpers/utilities
|-- dist/
|-- package.json
`-- vite.config.js

Backend-Frontend Integration Contract

1. Route contracts come from routes/api.php and must be mirrored in frontend-source/src/api.
2. Use consistent response envelope (status, message, data).
3. Feature-gated APIs must have matching frontend permission/feature checks.
4. If endpoint/method changes, update both React API client and UI module flows.

Where to Edit (Practical Mapping)

Important Notes

• This project does not use legacy routes/admin.php or routes/organizer.php structure.
• All modern API documentation should reference versioned endpoints under /api/v1.
• Use SQL dump and migration files together when debugging schema-level issues.