# mahonrisiu/localizador-buses-bluefields architecture

> Architecture diagram of the GitHub repository mahonrisiu/localizador-buses-bluefields, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mahonrisiu/localizador-buses-bluefields
- Repository: https://github.com/mahonrisiu/localizador-buses-bluefields

## Overview

#### Purpose and runtime
SIGBU/MiBus is a PHP/MySQL bus-location web application for Bluefields. It serves a public live-map experience, a bus-mounted location transmitter (“emisor”), and an administrator workspace. It runs under Apache/PHP with MySQL, intended for XAMPP; browser Geolocation supplies GPS and Leaflet renders maps.

Core bootstrap and persistence: `index.php`, `config/database.php`, `config/database.sql`.

#### Entry points and role boundary
Role-specific public endpoints form the application boundary:
- Public rider map: `public/usuario/index.php`
- Emisor login and tracking panel: `public/emisor/login.php`, `public/emisor/panel.php`
- Administrator login, panel, and management: `public/admin/login.php`, `public/admin/panel.php`, `public/admin/gestion.php`

The user role is read-only and unauthenticated. Emisor access uses a bus-associated access code; admin access uses credential login. Protected server pages and their endpoints enforce separation rather than exposing one shared UI.

#### MVC application layer
Controllers coordinate HTTP requests, authorization-related actions, and model operations:
- Bus/routing queries: `app/controllers/BusController.php`
- GPS-emitter operations: `app/controllers/EmisorController.php`
- Administrative operations: `app/controllers/AdminController.php`

Database-facing domain entities are separated into models for buses, routes, users/admin identities, and emitters: `app/models/Bus.php`, `app/models/Ruta.php`, `app/models/Usuario.php`, `app/models/Emisor.php`.

#### Live-location flow
An authorized emitter opens its panel; browser JavaScript obtains location from the Geolocation API and submits updates to the PHP update endpoint. The backend associates the update with the authenticated/assigned emitter and bus, then persists current location in MySQL.

Key flow paths: `public/emisor/panel.php`, `assets/js/emisor.js`, `public/emisor_actualizar.php`, `app/controllers/EmisorController.php`.

This is request/poll-based PHP/MySQL architecture, not the earlier Firebase Realtime Database approach.

#### Public map and data-read API
The public map page loads Leaflet-oriented client code, retrieves buses and routes through lightweight PHP endpoints, then displays bus positions and route context. Route-specific lookup supports filtering or focused map views.

Key paths: `public/usuario/index.php`, `assets/js/mapa.js`, `public/obtener_bus.php`, `public/obtener_bus_por_ruta.php`, `public/obtener_rutas.php`.

The browser/API boundary is important: map rendering and polling behavior live client-side, while PHP endpoints expose database-backed transport data.

#### Administration and route lifecycle
Admin pages provide operational control over routes and related transport entities. Dedicated endpoints create/remove routes, toggle route availability, and return complete route data for management UI updates.

Key paths: `public/admin/gestion.php`, `public/admin_agregar_ruta.php`, `public/admin_eliminar_ruta.php`, `public/admin_toggle_ruta.php`, `public/admin_obtener_rutas_completas.php`.

`app/controllers/AdminController.php` is the intended orchestration point between these actions and route/bus/emitter models.

#### Infrastructure and assets
MySQL schema and connection configuration are repository-managed, while Apache/PHP is the serving runtime. Frontend styling and shared browser utilities are static assets; `public/asset.php` likely mediates asset delivery or resolution.

Key paths: `config/database.php`, `config/database.sql`, `assets/css/estilos.css`, `assets/js/utilidades.js`, `public/asset.php`.

Main entry points: [`app/models/Bus.php`](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/models/Bus.php) (Bus and route models), [`app/controllers/EmisorController.php`](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/EmisorController.php) (Emisor controller), [`app/controllers/AdminController.php`](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/AdminController.php) (Admin controller), [`assets/js/mapa.js`](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/assets/js/mapa.js) (Map client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["PHP entry points"]
  node_rider["Rider map page<br/>public page<br/>[index.php]"]
  node_emisor_panel["Emisor panel<br/>protected page<br/>[panel.php]"]
  node_admin_pages["Admin workspace<br/>protected pages<br/>[gestion.php]"]
  node_location_update["Location update API<br/>PHP endpoint"]
  node_transport_api["Transport read APIs<br/>PHP endpoints<br/>[obtener_bus.php]"]
  node_route_admin_api["Route admin APIs<br/>PHP endpoints"]
end

subgraph group_app["Application layer"]
  node_bus_controller["Bus controller<br/>PHP controller<br/>[BusController.php]"]
  node_emisor_controller["Emisor controller<br/>PHP controller"]
  node_admin_controller["Admin controller<br/>PHP controller"]
  node_transport_models["Bus and route models<br/>PHP models<br/>[Bus.php]"]
  node_identity_emitter_models["Identity and emitter models<br/>PHP models<br/>[Emisor.php]"]
end

subgraph group_client["Browser clients"]
  node_map_client["Map client<br/>browser JavaScript<br/>[mapa.js]"]
  node_emisor_client["Emitter client<br/>browser JavaScript<br/>[emisor.js]"]
  node_geolocation{{"Browser Geolocation<br/>browser API"}}
  node_leaflet{{"Leaflet<br/>map library"}}
end

subgraph group_data["Persistence"]
  node_db_config["Database connection<br/>PHP configuration<br/>[database.php]"]
  node_mysql[("MySQL transport data<br/>database<br/>[database.sql]")]
end

node_rider -->|"loads"| node_map_client
node_map_client -->|"polls"| node_transport_api
node_map_client -->|"renders with"| node_leaflet
node_emisor_panel -->|"loads"| node_emisor_client
node_emisor_client -->|"reads GPS"| node_geolocation
node_emisor_client -->|"submits coordinates"| node_location_update
node_location_update -->|"dispatches"| node_emisor_controller
node_transport_api -->|"queries"| node_bus_controller
node_admin_pages -->|"manages routes"| node_route_admin_api
node_route_admin_api -->|"dispatches"| node_admin_controller
node_bus_controller -->|"uses"| node_transport_models
node_emisor_controller -->|"authorizes and associates"| node_identity_emitter_models
node_emisor_controller -->|"updates bus location"| node_transport_models
node_admin_controller -->|"manages"| node_transport_models
node_admin_controller -->|"manages related entities"| node_identity_emitter_models
node_transport_models -->|"connects through"| node_db_config
node_identity_emitter_models -->|"connects through"| node_db_config
node_db_config -->|"accesses"| node_mysql

click node_rider "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/usuario/index.php"
click node_emisor_panel "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/emisor/panel.php"
click node_admin_pages "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/admin/gestion.php"
click node_location_update "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/emisor_actualizar.php"
click node_transport_api "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/obtener_bus.php"
click node_route_admin_api "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/admin_agregar_ruta.php"
click node_map_client "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/assets/js/mapa.js"
click node_emisor_client "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/assets/js/emisor.js"
click node_bus_controller "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/BusController.php"
click node_emisor_controller "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/EmisorController.php"
click node_admin_controller "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/AdminController.php"
click node_transport_models "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/models/Bus.php"
click node_identity_emitter_models "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/models/Emisor.php"
click node_db_config "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/config/database.php"
click node_mysql "https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/config/database.sql"

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_rider,node_emisor_panel,node_admin_pages,node_location_update,node_transport_api,node_route_admin_api toneBlue
class node_bus_controller,node_emisor_controller,node_admin_controller,node_transport_models,node_identity_emitter_models toneAmber
class node_map_client,node_emisor_client,node_geolocation,node_leaflet toneMint
class node_db_config,node_mysql toneRose
```

## Components

### PHP entry points

Role-specific pages and lightweight HTTP endpoints.

- [Rider map page](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/usuario/index.php): public page · Unauthenticated read-only live map. · `public/usuario/index.php`
- [Emisor panel](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/emisor/panel.php): protected page · Bus-associated access-code tracking workspace. · `public/emisor/panel.php`
- [Admin workspace](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/admin/gestion.php): protected pages · Login, panel, and route management. · `public/admin/gestion.php`
- [Location update API](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/emisor_actualizar.php): PHP endpoint · Accepts authorized emitter GPS updates. · `public/emisor_actualizar.php`
- [Transport read APIs](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/obtener_bus.php): PHP endpoints · Bus, route-filtered bus, and route data. · `public/obtener_bus.php`
- [Route admin APIs](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/public/admin_agregar_ruta.php): PHP endpoints · Create, remove, toggle, and list routes. · `public/admin_agregar_ruta.php`

### Application layer

Controllers and domain models.

- [Bus controller](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/BusController.php): PHP controller · Coordinates bus and routing queries. · `app/controllers/BusController.php`
- [Emisor controller](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/EmisorController.php): PHP controller · Authorizes emitter operations and location updates. · `app/controllers/EmisorController.php`
- [Admin controller](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/controllers/AdminController.php): PHP controller · Orchestrates administrative transport actions. · `app/controllers/AdminController.php`
- [Bus and route models](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/models/Bus.php): PHP models · Bus and route persistence entities. · `app/models/Bus.php`
- [Identity and emitter models](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/app/models/Emisor.php): PHP models · Admin identity and bus-emitter associations. · `app/models/Emisor.php`

### Browser clients

Client-side map and GPS behavior.

- [Map client](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/assets/js/mapa.js): browser JavaScript · Leaflet rendering and bus polling. · `assets/js/mapa.js`
- [Emitter client](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/assets/js/emisor.js): browser JavaScript · Captures and submits browser GPS. · `assets/js/emisor.js`
- **Browser Geolocation**: browser API · Supplies device coordinates.
- **Leaflet**: map library · Renders map and route context.

### Persistence

Repository-managed MySQL access and schema.

- [Database connection](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/config/database.php): PHP configuration · MySQL connection setup. · `config/database.php`
- [MySQL transport data](https://github.com/mahonrisiu/localizador-buses-bluefields/blob/main/config/database.sql): database · Current locations, buses, routes, users, and emitters. · `config/database.sql`

## Connections

- Rider map page → Map client: loads
- Map client → Transport read APIs: polls
- Map client → Leaflet: renders with
- Emisor panel → Emitter client: loads
- Emitter client → Browser Geolocation: reads GPS
- Emitter client → Location update API: submits coordinates
- Location update API → Emisor controller: dispatches
- Transport read APIs → Bus controller: queries
- Admin workspace → Route admin APIs: manages routes
- Route admin APIs → Admin controller: dispatches
- Bus controller → Bus and route models: uses
- Emisor controller → Identity and emitter models: authorizes and associates
- Emisor controller → Bus and route models: updates bus location
- Admin controller → Bus and route models: manages
- Admin controller → Identity and emitter models: manages related entities
- Bus and route models → Database connection: connects through
- Identity and emitter models → Database connection: connects through
- Database connection → MySQL transport data: accesses