# jesusescalante/topgol architecture

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

- Interactive diagram: https://gitdiagram.com/jesusescalante/topgol
- Repository: https://github.com/jesusescalante/topgol

## Overview

TOP GOL is a PHP MVC platform for sports-complex reservations and administration. The main workflow runs from a customer’s web request through the front controller and router to reservation handling, availability checks, and reservation records; payment and notification handling support that flow. Separate administrative branches manage facilities, event spaces, POS sales, inventory, and financial reporting. The README also documents Google OAuth and Telegram notifications. Relationships below follow shown routes, excerpts, source-index references, and README capabilities; several subsystem internals were not sampled.

Main entry points: [`app/Controllers/ReservaController.php`](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/ReservaController.php) (Reservation workflow), [`app/Models/Venta.php`](https://github.com/jesusescalante/topgol/blob/main/app/Models/Venta.php) (Sales transactions), [`app/Models/Pago.php`](https://github.com/jesusescalante/topgol/blob/main/app/Models/Pago.php) (Payment records), [`app/Models/Producto.php`](https://github.com/jesusescalante/topgol/blob/main/app/Models/Producto.php) (Product inventory)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_front["HTTP entry<br/>[index.php]"]
  node_router["Route dispatch<br/>[Router.php]"]
  node_base_controller["Controller base<br/>[Controller.php]"]
  node_auth["Authentication<br/>[AuthController.php]"]
end

subgraph group_booking["Reservations and facilities"]
  node_booking_controller["Reservation workflow"]
  node_facility_controller["Court management"]
  node_space_controller["Event spaces"]
  node_reservation_model["Reservation records<br/>[Reserva.php]"]
  node_court_model["Court availability<br/>[Cancha.php]"]
  node_space_model["Space records<br/>[Espacio.php]"]
end

subgraph group_business["Operations and finance"]
  node_payment_controller["Payments and till<br/>[PagoController.php]"]
  node_payment_model["Payment records<br/>[Pago.php]"]
  node_pos_controller["POS sales"]
  node_sales_model["Sales transactions<br/>[Venta.php]"]
  node_product_controller["Catalog and stock"]
  node_product_model["Product inventory<br/>[Producto.php]"]
  node_inventory_ledger["Inventory ledger"]
  node_dashboard["Admin dashboard"]
  node_reports["Financial reports"]
end

subgraph group_data["Data and integrations"]
  node_oauth["Google OAuth<br/>[GoogleOAuth.php]"]
  node_notifications["Notifications<br/>[Notificacion.php]"]
  node_telegram["Telegram alerts"]
  node_model_base["PDO model layer<br/>[Model.php]"]
  node_database[("MySQL database<br/>[Database.php]")]
end

node_customer(("Customer / staff"))
node_google(("Google"))
node_telegram_api(("Telegram / CallMeBot"))

node_customer -->|"sends request"| node_front
node_front -->|"dispatches routes"| node_router
node_router -->|"routes reservations"| node_booking_controller
node_router -->|"routes authentication"| node_auth
node_booking_controller -->|"extends"| node_base_controller
node_auth -->|"extends"| node_base_controller
node_auth -->|"uses OAuth"| node_oauth
node_google -.->|"authenticates"| node_oauth
node_booking_controller -->|"checks courts"| node_court_model
node_booking_controller -->|"creates reservations"| node_reservation_model
node_booking_controller -->|"records advances"| node_payment_model
node_booking_controller -->|"sends reservation alert"| node_telegram
node_facility_controller -->|"manages courts"| node_court_model
node_space_controller -->|"manages spaces"| node_space_model
node_space_controller -->|"sends alerts"| node_telegram
node_payment_controller -->|"handles payments"| node_payment_model
node_pos_controller -->|"records sales"| node_sales_model
node_product_controller -->|"manages products"| node_product_model
node_sales_model -->|"updates stock"| node_product_model
node_sales_model -->|"records movements"| node_inventory_ledger
node_product_model -->|"records adjustments"| node_inventory_ledger
node_dashboard -->|"summarizes sales"| node_sales_model
node_dashboard -->|"checks stock"| node_product_model
node_reports -->|"queries income"| node_payment_model
node_reports -->|"queries sales"| node_sales_model
node_booking_controller -->|"uses notices"| node_notifications
node_telegram -->|"sends messages"| node_telegram_api
node_reservation_model -->|"synchronizes payments"| node_payment_model
node_reservation_model -->|"checks conflicts"| node_court_model
node_payment_model -->|"inherits data access"| node_model_base
node_model_base -->|"gets PDO connection"| node_database

click node_front "https://github.com/jesusescalante/topgol/blob/main/public/index.php"
click node_router "https://github.com/jesusescalante/topgol/blob/main/app/Core/Router.php"
click node_base_controller "https://github.com/jesusescalante/topgol/blob/main/app/Core/Controller.php"
click node_auth "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/AuthController.php"
click node_oauth "https://github.com/jesusescalante/topgol/blob/main/app/Services/GoogleOAuth.php"
click node_booking_controller "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/ReservaController.php"
click node_facility_controller "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/CanchaController.php"
click node_space_controller "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/EspacioController.php"
click node_reservation_model "https://github.com/jesusescalante/topgol/blob/main/app/Models/Reserva.php"
click node_court_model "https://github.com/jesusescalante/topgol/blob/main/app/Models/Cancha.php"
click node_space_model "https://github.com/jesusescalante/topgol/blob/main/app/Models/Espacio.php"
click node_payment_controller "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/PagoController.php"
click node_payment_model "https://github.com/jesusescalante/topgol/blob/main/app/Models/Pago.php"
click node_pos_controller "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/VentaController.php"
click node_sales_model "https://github.com/jesusescalante/topgol/blob/main/app/Models/Venta.php"
click node_product_controller "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/ProductoController.php"
click node_product_model "https://github.com/jesusescalante/topgol/blob/main/app/Models/Producto.php"
click node_inventory_ledger "https://github.com/jesusescalante/topgol/blob/main/app/Models/MovimientoInventario.php"
click node_dashboard "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/UsuarioController.php"
click node_reports "https://github.com/jesusescalante/topgol/blob/main/app/Controllers/ReporteController.php"
click node_notifications "https://github.com/jesusescalante/topgol/blob/main/app/Models/Notificacion.php"
click node_telegram "https://github.com/jesusescalante/topgol/blob/main/app/Services/TelegramNotifier.php"
click node_model_base "https://github.com/jesusescalante/topgol/blob/main/app/Core/Model.php"
click node_database "https://github.com/jesusescalante/topgol/blob/main/app/Config/Database.php"

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_front,node_router,node_base_controller,node_auth toneBlue
class node_booking_controller,node_facility_controller,node_space_controller,node_reservation_model,node_court_model,node_space_model toneAmber
class node_payment_controller,node_payment_model,node_pos_controller,node_sales_model,node_product_controller,node_product_model,node_inventory_ledger,node_dashboard,node_reports toneMint
class node_oauth,node_notifications,node_telegram,node_model_base,node_database toneRose
class node_customer,node_google,node_telegram_api toneIndigo
```

## Components

### Web application

- [HTTP entry](https://github.com/jesusescalante/topgol/blob/main/public/index.php): `public/index.php`
- [Route dispatch](https://github.com/jesusescalante/topgol/blob/main/app/Core/Router.php): `app/Core/Router.php`
- [Controller base](https://github.com/jesusescalante/topgol/blob/main/app/Core/Controller.php): `app/Core/Controller.php`
- [Authentication](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/AuthController.php): `app/Controllers/AuthController.php`

### Reservations and facilities

- [Reservation workflow](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/ReservaController.php): `app/Controllers/ReservaController.php`
- [Court management](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/CanchaController.php): `app/Controllers/CanchaController.php`
- [Event spaces](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/EspacioController.php): `app/Controllers/EspacioController.php`
- [Reservation records](https://github.com/jesusescalante/topgol/blob/main/app/Models/Reserva.php): `app/Models/Reserva.php`
- [Court availability](https://github.com/jesusescalante/topgol/blob/main/app/Models/Cancha.php): `app/Models/Cancha.php`
- [Space records](https://github.com/jesusescalante/topgol/blob/main/app/Models/Espacio.php): `app/Models/Espacio.php`

### Operations and finance

- [Payments and till](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/PagoController.php): `app/Controllers/PagoController.php`
- [Payment records](https://github.com/jesusescalante/topgol/blob/main/app/Models/Pago.php): `app/Models/Pago.php`
- [POS sales](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/VentaController.php): `app/Controllers/VentaController.php`
- [Sales transactions](https://github.com/jesusescalante/topgol/blob/main/app/Models/Venta.php): `app/Models/Venta.php`
- [Catalog and stock](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/ProductoController.php): `app/Controllers/ProductoController.php`
- [Product inventory](https://github.com/jesusescalante/topgol/blob/main/app/Models/Producto.php): `app/Models/Producto.php`
- [Inventory ledger](https://github.com/jesusescalante/topgol/blob/main/app/Models/MovimientoInventario.php): `app/Models/MovimientoInventario.php`
- [Admin dashboard](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/UsuarioController.php): `app/Controllers/UsuarioController.php`
- [Financial reports](https://github.com/jesusescalante/topgol/blob/main/app/Controllers/ReporteController.php): `app/Controllers/ReporteController.php`

### Data and integrations

- [Google OAuth](https://github.com/jesusescalante/topgol/blob/main/app/Services/GoogleOAuth.php): `app/Services/GoogleOAuth.php`
- [Notifications](https://github.com/jesusescalante/topgol/blob/main/app/Models/Notificacion.php): `app/Models/Notificacion.php`
- [Telegram alerts](https://github.com/jesusescalante/topgol/blob/main/app/Services/TelegramNotifier.php): `app/Services/TelegramNotifier.php`
- [PDO model layer](https://github.com/jesusescalante/topgol/blob/main/app/Core/Model.php): `app/Core/Model.php`
- [MySQL database](https://github.com/jesusescalante/topgol/blob/main/app/Config/Database.php): `app/Config/Database.php`

### Other components

- **Customer / staff**
- **Google**
- **Telegram / CallMeBot**

## Connections

- Customer / staff → HTTP entry: sends request (evidence: `README.md`)
- HTTP entry → Route dispatch: dispatches routes (evidence: `public/index.php`)
- Route dispatch → Reservation workflow: routes reservations (evidence: `public/index.php`)
- Route dispatch → Authentication: routes authentication (evidence: `public/index.php`)
- Reservation workflow → Controller base: extends (evidence: `app/Controllers/ReservaController.php`)
- Authentication → Controller base: extends (evidence: `app/Controllers/AuthController.php`)
- Authentication → Google OAuth: uses OAuth (evidence: `app/Controllers/AuthController.php`)
- Google → Google OAuth: authenticates (evidence: `README.md`)
- Reservation workflow → Court availability: checks courts (evidence: `app/Controllers/ReservaController.php`)
- Reservation workflow → Reservation records: creates reservations (evidence: `app/Controllers/ReservaController.php`)
- Reservation workflow → Payment records: records advances (evidence: `app/Controllers/ReservaController.php`)
- Reservation workflow → Telegram alerts: sends reservation alert (evidence: `app/Controllers/ReservaController.php`)
- Court management → Court availability: manages courts (evidence: `app/Controllers/CanchaController.php`)
- Event spaces → Space records: manages spaces (evidence: `app/Controllers/EspacioController.php`)
- Event spaces → Telegram alerts: sends alerts (evidence: `app/Controllers/EspacioController.php`)
- Payments and till → Payment records: handles payments (evidence: `app/Controllers/PagoController.php`)
- POS sales → Sales transactions: records sales (evidence: `app/Controllers/VentaController.php`)
- Catalog and stock → Product inventory: manages products (evidence: `app/Controllers/ProductoController.php`)
- Sales transactions → Product inventory: updates stock (evidence: `app/Models/Venta.php`)
- Sales transactions → Inventory ledger: records movements (evidence: `app/Models/Venta.php`)
- Product inventory → Inventory ledger: records adjustments (evidence: `app/Models/Producto.php`)
- Admin dashboard → Sales transactions: summarizes sales (evidence: `app/Controllers/UsuarioController.php`)
- Admin dashboard → Product inventory: checks stock (evidence: `app/Controllers/UsuarioController.php`)
- Financial reports → Payment records: queries income (evidence: `app/Controllers/ReporteController.php`)
- Financial reports → Sales transactions: queries sales (evidence: `app/Controllers/ReporteController.php`)
- Reservation workflow → Notifications: uses notices (evidence: `app/Controllers/ReservaController.php`)
- Telegram alerts → Telegram / CallMeBot: sends messages (evidence: `README.md`)
- Reservation records → Payment records: synchronizes payments (evidence: `app/Models/Reserva.php`)
- Reservation records → Court availability: checks conflicts (evidence: `app/Models/Reserva.php`)
- Payment records → PDO model layer: inherits data access (evidence: `app/Models/Pago.php`)
- PDO model layer → MySQL database: gets PDO connection (evidence: `app/Core/Model.php`)