# angelabrilq/megaunistore architecture

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

- Interactive diagram: https://gitdiagram.com/angelabrilq/megaunistore
- Repository: https://github.com/angelabrilq/megaunistore

## Overview

1. **Overall shape**
   - This repository is a **two-part PHP application**: a server-side backend for the operational system and a separate frontend site for public/marketing pages.
   - The codebase is **not a single SPA** in the repository contents; despite the README’s mention of React, the checked-in frontend is mostly **PHP/HTML static pages** plus shared layout fragments.

2. **Backend runtime and entry point**
   - The backend is served from `backend/public/index.php`, which acts as the **front controller**.
   - Requests are then routed through `backend/routes/web.php` into controller classes under `backend/app/controllers`.
   - Configuration is centralized in `backend/config/env.php` and `backend/config/database.php`, indicating a classic PHP application with environment-driven DB settings.

3. **Layered backend structure**
   - The backend follows a clear **controller → model → database** pattern.
   - Controllers coordinate request handling and view rendering.
   - Models in `backend/app/models` represent the business entities and likely encapsulate DB access and domain logic.
   - `ControllerHelper.php` suggests shared controller utilities, probably for responses, redirects, or common checks.

4. **Core business subsystems**
   - The repository is organized around a multistore/retail management domain with separate modules for:
     - **Authentication and users**: `AuthController`, `UsuarioController`, `Rol`, `Permiso`
     - **Sales**: `VentaController`, `MetodoPago`, `Cupon`
     - **Cash register**: `CajaController`
     - **Inventory**: `InventarioController`, `Producto`, `Inventario`
     - **Catalogs/master data**: `Categoria`, `Proveedor`, `UnidadMedida`, `Impuesto`, `Tienda`
     - **People management**: `Cliente`, `Empleado`
     - **Returns and reporting**: `Devolucion`, `Reporte`
     - **System setup**: `SetupController`
   - These modules are the main architectural boundaries for an implementation diagram.

5. **Authorization and roles**
   - The presence of `Rol` and `Permiso` models plus a `dashboard` view set by role shows a **role-based access control** design.
   - Role-specific dashboard pages exist for different operational personas: `superadmin`, `sistema`, `admin_tienda`, `supervisor`, `vendedor`, `bodeguero`, `reportero`, `nomina`, and `cliente`.
   - This implies the backend gates both navigation and business actions based on user permissions.

6. **Views and rendering model**
   - Backend views live in `backend/resources/views`, organized by module.
   - This is a **server-rendered UI** approach: controllers select PHP views such as `ventas/index.php`, `inventario/movimientos.php`, `usuarios/asignar_rol.php`, etc.
   - Shared layout templates exist under `backend/resources/views/layout` and `dashboard`, so the backend likely uses template composition rather than client-side rendering.

7. **Data and persistence**
   - Database schema is defined through SQL files: `backend/database/fase3_migracion.sql` and the top-level `backup.sql`.
   - This indicates the schema is a major part of the repo and likely the primary source of truth for tables and relationships.
   - The model set closely mirrors the domain tables, so persistence is structured around relational entities for products, stores, sales, inventory, users, and transactions.

8. **Operational flows**
   - The main transaction path is likely: **user logs in → lands on role dashboard → performs sales, inventory, or cash operations → controllers update models/database → views show current state**.
   - Inventory and sales are tightly coupled through products, stock movements, cash register actions, and reports.
   - Returns (`devoluciones`) and coupons add post-sale adjustments to the commerce flow.

9. **Public/frontend site**
   - The `frontend/public` directory contains pages such as `index.php`, `planes.php`, `soluciones.php`, `contacto.php`, and `testimonios.php`.
   - This looks like a **public website / product marketing layer**, separate from the administrative backend.
   - Shared fragments in `frontend/src/layout` suggest a templated site shell for header/footer/navigation.

10. **Boundary between public site and admin system**
   - The frontend and backend are separated by directory and responsibility:
     - **Frontend**: informational pages, product/solution presentation, and public-facing content.
     - **Backend**: authenticated business operations and data management.
   - There is no evidence in the tree of a shared API consumed by a JS frontend; instead the system appears to rely on server-rendered PHP on both sides.

11. **Error handling and resilience**
   - The backend includes explicit error views for **403** and **404**, which indicates route-level and authorization-aware failure handling.
   - This is consistent with a protected admin system where access denials and missing routes are expected runtime conditions.

12. **Documentation as part of the architecture**
   - The `document/` folder contains implementation notes, installation guides, architecture docs, and user/manual technical documentation.
   - There is also a file named `ANALISIS_REQUERIMIENTOS_VS_IMPLEMENTACION.md`, suggesting the repo includes **requirements traceability** and phase-based implementation control.
   - For architecture diagrams, this documentation likely reflects the intended module boundaries and deployment assumptions more explicitly than the README.

13. **What matters most for a diagram**
   - Show two top-level surfaces: **public site** and **authenticated backend**.
   - Inside the backend, show the main domains: auth/RBAC, sales, cash, inventory, catalogs, people, reporting, and system setup.
   - Place the database as a central relational store feeding all backend modules.
   - Treat the role-specific dashboards as presentation variants over the same backend domain services.

14. **Notable implementation mismatch**
   - The README says `frontend` is React.js and `backend` may be Node/PHP, but the repository contents indicate a **PHP-centric implementation** with server-rendered views.
   - If drawing the architecture from code, trust the file tree over the README: the actual shape is a **monolithic PHP backend plus a static/templated public frontend**, not a React SPA with a separate API layer.

Main entry points: [`backend/routes/web.php`](https://github.com/angelabrilq/megaunistore/blob/main/backend/routes/web.php) (Web routes), [`backend/app/models`](https://github.com/angelabrilq/megaunistore/tree/main/backend/app/models) (Domain models), [`backend/resources/views`](https://github.com/angelabrilq/megaunistore/tree/main/backend/resources/views) (Server views), [`backend/app/controllers/AuthController.php`](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/AuthController.php) (Auth/RBAC)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend site"]
  node_frontend_public["Public pages<br/>PHP site"]
  node_frontend_layout["Site shell<br/>layout fragments"]
end

subgraph group_backend["Backend app"]
  node_backend_entry["Front controller<br/>PHP entrypoint<br/>[index.php]"]
  node_backend_routes["Web routes<br/>routing<br/>[web.php]"]
  node_backend_config["Config"]
  node_backend_helpers["Controller helper<br/>shared utility"]
  node_backend_auth["Auth/RBAC<br/>controllers + models<br/>[AuthController.php]"]
  node_backend_sales["Sales<br/>controllers + models"]
  node_backend_cash["Cash desk<br/>controllers + model<br/>[CajaController.php]"]
  node_backend_inventory["Inventory<br/>controllers + models"]
  node_backend_catalogs["Catalogs<br/>controllers + models"]
  node_backend_people["People<br/>controllers + models"]
  node_backend_operations["Returns & reports<br/>controllers + models"]
  node_backend_setup["Setup<br/>controller"]
  node_backend_views["Server views<br/>PHP templates"]
  node_backend_errors["Error pages<br/>error views"]
  node_backend_models["Domain models<br/>entity models"]
  node_backend_db[("Relational DB<br/>mysql schema")]
end

subgraph group_docs["Documentation"]
  node_docs_pack["Docs pack"]
end

node_frontend_public -->|"uses shell"| node_frontend_layout
node_backend_entry -->|"dispatches"| node_backend_routes
node_backend_routes -->|"routes to"| node_backend_auth
node_backend_routes -->|"routes to"| node_backend_sales
node_backend_routes -->|"routes to"| node_backend_cash
node_backend_routes -->|"routes to"| node_backend_inventory
node_backend_routes -->|"routes to"| node_backend_catalogs
node_backend_routes -->|"routes to"| node_backend_people
node_backend_routes -->|"routes to"| node_backend_operations
node_backend_routes -->|"routes to"| node_backend_setup
node_backend_auth -->|"uses"| node_backend_models
node_backend_sales -->|"uses"| node_backend_models
node_backend_cash -->|"uses"| node_backend_models
node_backend_inventory -->|"uses"| node_backend_models
node_backend_catalogs -->|"uses"| node_backend_models
node_backend_people -->|"uses"| node_backend_models
node_backend_operations -->|"uses"| node_backend_models
node_backend_models -->|"persists to"| node_backend_db
node_backend_auth -->|"renders"| node_backend_views
node_backend_sales -->|"renders"| node_backend_views
node_backend_cash -->|"renders"| node_backend_views
node_backend_inventory -->|"renders"| node_backend_views
node_backend_people -->|"renders"| node_backend_views
node_backend_operations -->|"renders"| node_backend_views
node_backend_routes -->|"falls back to"| node_backend_errors
node_backend_auth -->|"uses"| node_backend_helpers
node_backend_config -->|"configures"| node_backend_db
node_docs_pack -.->|"documents"| node_backend_routes
node_docs_pack -.->|"documents"| node_backend_db

click node_frontend_public "https://github.com/angelabrilq/megaunistore/tree/main/frontend/public"
click node_frontend_layout "https://github.com/angelabrilq/megaunistore/tree/main/frontend/src/layout"
click node_backend_entry "https://github.com/angelabrilq/megaunistore/blob/main/backend/public/index.php"
click node_backend_routes "https://github.com/angelabrilq/megaunistore/blob/main/backend/routes/web.php"
click node_backend_config "https://github.com/angelabrilq/megaunistore/tree/main/backend/config"
click node_backend_helpers "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/Helpers/ControllerHelper.php"
click node_backend_auth "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/AuthController.php"
click node_backend_sales "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/VentaController.php"
click node_backend_cash "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/CajaController.php"
click node_backend_inventory "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/InventarioController.php"
click node_backend_catalogs "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/CategoriaController.php"
click node_backend_people "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/ClienteController.php"
click node_backend_operations "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/DevolucionController.php"
click node_backend_setup "https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/SetupController.php"
click node_backend_views "https://github.com/angelabrilq/megaunistore/tree/main/backend/resources/views"
click node_backend_errors "https://github.com/angelabrilq/megaunistore/tree/main/backend/resources/errors"
click node_backend_models "https://github.com/angelabrilq/megaunistore/tree/main/backend/app/models"
click node_backend_db "https://github.com/angelabrilq/megaunistore/blob/main/backend/database/fase3_migracion.sql"
click node_docs_pack "https://github.com/angelabrilq/megaunistore/tree/main/document"

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_frontend_public,node_frontend_layout toneBlue
class node_backend_entry,node_backend_routes,node_backend_config,node_backend_helpers,node_backend_auth,node_backend_sales,node_backend_cash,node_backend_inventory,node_backend_catalogs,node_backend_people,node_backend_operations,node_backend_setup,node_backend_views,node_backend_errors,node_backend_models,node_backend_db toneAmber
class node_docs_pack toneMint
```

## Components

### Frontend site

Public-facing marketing pages and shared shell.

- [Public pages](https://github.com/angelabrilq/megaunistore/tree/main/frontend/public): PHP site · Marketing and informational pages served from the public frontend. · `frontend/public`
- [Site shell](https://github.com/angelabrilq/megaunistore/tree/main/frontend/src/layout): layout fragments · Shared header, footer, and page composition for the public site. · `frontend/src/layout`

### Backend app

Authenticated operational system with server-rendered views.

- [Front controller](https://github.com/angelabrilq/megaunistore/blob/main/backend/public/index.php): PHP entrypoint · Main backend request entry at the public index. · `backend/public/index.php`
- [Web routes](https://github.com/angelabrilq/megaunistore/blob/main/backend/routes/web.php): routing · Dispatches backend requests to controllers. · `backend/routes/web.php`
- [Config](https://github.com/angelabrilq/megaunistore/tree/main/backend/config): env + db config · Environment and database configuration for the backend. · `backend/config`
- [Controller helper](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/Helpers/ControllerHelper.php): shared utility · Common controller-level utility functions. · `backend/app/Helpers/ControllerHelper.php`
- [Auth/RBAC](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/AuthController.php): controllers + models · Login, users, roles, and permissions. · `backend/app/controllers/AuthController.php`
- [Sales](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/VentaController.php): controllers + models · Sales flow, payment methods, coupons, and sale records. · `backend/app/controllers/VentaController.php`
- [Cash desk](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/CajaController.php): controllers + model · Cash opening, closing, and movement tracking. · `backend/app/controllers/CajaController.php`
- [Inventory](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/InventarioController.php): controllers + models · Products, stock movements, and inventory control. · `backend/app/controllers/InventarioController.php`
- [Catalogs](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/CategoriaController.php): controllers + models · Stores, categories, suppliers, units, and taxes. · `backend/app/controllers/CategoriaController.php`
- [People](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/ClienteController.php): controllers + models · Customers, employees, and user administration. · `backend/app/controllers/ClienteController.php`
- [Returns & reports](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/DevolucionController.php): controllers + models · Post-sale returns and operational reporting. · `backend/app/controllers/DevolucionController.php`
- [Setup](https://github.com/angelabrilq/megaunistore/blob/main/backend/app/controllers/SetupController.php): controller · Initial system setup and bootstrap flows. · `backend/app/controllers/SetupController.php`
- [Server views](https://github.com/angelabrilq/megaunistore/tree/main/backend/resources/views): PHP templates · Module views and role dashboards rendered by controllers. · `backend/resources/views`
- [Error pages](https://github.com/angelabrilq/megaunistore/tree/main/backend/resources/errors): error views · 403 and 404 response pages for access and routing failures. · `backend/resources/errors`
- [Domain models](https://github.com/angelabrilq/megaunistore/tree/main/backend/app/models): entity models · Relational entities for users, stores, products, sales, inventory, and transactions. · `backend/app/models`
- [Relational DB](https://github.com/angelabrilq/megaunistore/blob/main/backend/database/fase3_migracion.sql): mysql schema · Primary persistence layer defined by migration SQL and backup schema. · `backend/database/fase3_migracion.sql`

### Documentation

Implementation notes, manuals, and architecture references.

- [Docs pack](https://github.com/angelabrilq/megaunistore/tree/main/document): docs · Architecture, installation, manual, and implementation notes. · `document`

## Connections

- Public pages → Site shell: uses shell · Public pages compose shared layout fragments.
- Front controller → Web routes: dispatches · The front controller hands requests to the route table.
- Web routes → Auth/RBAC: routes to · Authentication and role-related requests go to auth controllers.
- Web routes → Sales: routes to · Sales actions are handled by the sales controller set.
- Web routes → Cash desk: routes to · Cash register operations are routed here.
- Web routes → Inventory: routes to · Inventory requests are routed here.
- Web routes → Catalogs: routes to · Catalog and master-data requests are routed here.
- Web routes → People: routes to · People and admin requests are routed here.
- Web routes → Returns & reports: routes to · Returns and reporting requests are routed here.
- Web routes → Setup: routes to · Initial setup requests are routed here.
- Auth/RBAC → Domain models: uses · Auth, roles, permissions, and users are persisted through models.
- Sales → Domain models: uses · Sales and coupon/payment data flow through the domain models.
- Cash desk → Domain models: uses · Cash movements are stored via models.
- Inventory → Domain models: uses · Inventory and product state is handled by models.
- Catalogs → Domain models: uses · Catalog/master data is represented by models.
- People → Domain models: uses · User, customer, and employee data use models.
- Returns & reports → Domain models: uses · Returns and reports are backed by models.
- Domain models → Relational DB: persists to · Models read and write the relational database.
- Auth/RBAC → Server views: renders · Auth flows render server-side pages.
- Sales → Server views: renders · Sales screens and receipts are server-rendered.
- Cash desk → Server views: renders · Cash desk screens are server-rendered.
- Inventory → Server views: renders · Inventory screens are server-rendered.
- People → Server views: renders · User, client, and employee screens are server-rendered.
- Returns & reports → Server views: renders · Reports and return screens are server-rendered.
- Web routes → Error pages: falls back to · Missing routes and denied access use dedicated error views.
- Auth/RBAC → Controller helper: uses · Controllers share common helper utilities.
- Config → Relational DB: configures · Environment settings drive database access.
- Docs pack → Web routes: documents · Architecture and manuals describe backend behavior and flow.
- Docs pack → Relational DB: documents · Database and implementation notes document the schema.