# kmoore1616/gunnison-gps-tour architecture

> Architecture diagram of the GitHub repository kmoore1616/gunnison-gps-tour, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kmoore1616/gunnison-gps-tour
- Repository: https://github.com/kmoore1616/gunnison-gps-tour

## Overview

##### Project type & purpose (what you’re diagramming)
This is a **single-service monolithic Flask web application** that:
- Serves **server-rendered HTML pages** (Jinja templates) for browsing **Tours/Places** and viewing a **tour-specific walking route**.
- Uses **SQLite** as the system of record for tours/places/reviews (including ordering stops via `tour_places`).
- Uses the **Google Maps JS API** in the browser to render an interactive map, and the backend exposes an endpoint (`/get_tour_poly/<tour_id>`) that returns **encoded polylines** (route geometry) for drawing.

- Browser → Flask app (HTTP routes)
- Flask app → SQLite (CRUD & relationships)
- Browser → Google Maps (JS API) and/or Flask app → Google services (if routes are computed server-side; at minimum the API key is injected for client-side usage)
- Admin pages as a separate “role” and route group, but still within the same Flask service.

##### File structure analysis (how the code is organized)
From the tree:

- `app.py`
The entire backend is likely here: Flask app creation, route handlers, SQLAlchemy models (or at least DB access), authentication (hinted by `flask-login` dependency), and the `/get_tour_poly/<tour_id>` endpoint.

- `instance/gps-database.sqlite`

- `templates/*.html`
Jinja templates (server-rendered UI). Notable groups:
- Visitor: `home.html`, `tour_list.html`, `places.html`, `viewTour.html`, `onTour.html`, `contact.html`, nav templates (`visitornav.html`)
- Admin: `adminlogin.html`, `adminhome.html`, `edittours.html`, `adminfeedback.html`, `adminreviews.html`, nav (`adminnav.html`)

- `static/*.js, *.css`
Frontend behavior and styling:
- `static/map.js` and `static/index.js` likely drive map rendering + AJAX/fetch calls to `/get_tour_poly/<tour_id>`.
- CSS files for layout/branding.

**Architectural implication:** this is a classic Flask MVC-ish setup:
- “Views” = `templates/`
- “Controller/routes” = `app.py`
- “Model/persistence” = SQLite (+ SQLAlchemy)

##### README insights (runtime and dependencies)
Key dependencies called out:
- `flask`, `flask-sqlalchemy` → web + ORM/persistence
- `flask-login` → admin authentication/session management
- `python-dotenv` → configuration via `.env` (`MAPS_API_KEY`)
- `requests` → indicates backend may call external HTTP services (potentially Google Directions API, or something else)

Key endpoints / pages called out:
- Visitor routes: `/`, `/Tours`, `/Places`, `/Tour`, `/Contact`, `/viewTour/<tour_id>`
- Admin: `/adminhome`, `/edittours`, `/adminfeedback`, `/adminreviews`
- Data endpoint: `/get_tour_poly/<tour_id>` (polyline payload for map drawing)

- Page rendering endpoints (HTML)
- JSON/data endpoint(s) consumed by JS
- Authentication boundary for admin routes
- External API key/config injection

##### Client / Browser
- “Visitor User”
- “Admin User” (same browser tech, different role/permissions)

##### Flask Web App (app.py)
- **Route Handlers (HTTP)**: visitor pages + admin pages + `/get_tour_poly/<tour_id>`
- **Auth/Session**: Flask-Login (admin login, session cookie)
- **DB Access Layer**: SQLAlchemy (models/queries)
- **Polyline/Route Service**: the logic that produces encoded polylines (may be DB-backed or computed/cached)

##### SQLite Database (`instance/gps-database.sqlite`)
- `tours`
- `places`
- `reviews`
- `tour_places` (join table that **orders stops**)

##### Google Maps Platform (External)
- **Google Maps JavaScript API** (loaded by browser using `MAPS_API_KEY`)

##### Configuration / Secrets
- `.env` providing `MAPS_API_KEY` to server-side template rendering or runtime config (represent this as “Environment/Config” feeding the Flask app)

##### Browser → Flask
- `GET /` `/Tours` `/Places` `/Contact` `/viewTour/<tour_id>`
- Admin:
- `GET/POST /adminlogin` (implied by template)
- `GET /adminhome`, `/edittours`, `/adminfeedback`, `/adminreviews`
- Data:
- `GET /get_tour_poly/<tour_id>`

##### Flask → SQLite
- For visitor pages: read tours, places, ordered stops
- For admin pages: CRUD tours/places, moderate reviews/feedback

##### Browser → Google Maps
- Loads Maps JS + tiles + renders map

##### (Optional/if applicable) Flask → Google Web Service
- If the backend computes routes, it might call Directions API and then store/return encoded polyline

##### Flask ↔ Config (.env)
- At startup: loads `MAPS_API_KEY` via dotenv

##### Important patterns / principles used
- **Server-rendered web app** (Jinja templates)
- **Role-based admin vs visitor flows** (same service, different endpoints + auth)
- **Thin JS client** that fetches route polyline and draws on Google Map
- **Relational data model** with an ordering join table (`tour_places`) as a key domain concept

##### Relevant technologies in labels
- “Flask (Python)”
- “Flask-SQLAlchemy”
- “Flask-Login”
- “SQLite”
- “Jinja2 templates”
- “Google Maps JavaScript API”
- “dotenv (.env)”

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =======================
%% Actors / Clients
%% =======================
subgraph "Clients"
direction TB
VisitorUser["Visitor User"]:::actor
AdminUser["Admin User"]:::actor
Browser["Web Browser<br/>(HTML + JS + Cookies)"]:::client
VisitorUser -->|"uses"| Browser
AdminUser -->|"uses"| Browser
end

%% =======================
%% Frontend Assets & UI
%% =======================
subgraph "Frontend (Server-rendered UI + Static Assets)"
direction TB

subgraph "Jinja Templates (templates/)"
direction TB
BaseTpl["base.html<br/>(Layout)"]:::template
VisitorTpls["Visitor Templates<br/>home/tours/places/contact/viewTour/onTour/nav"]:::template
AdminTpls["Admin Templates<br/>adminlogin/adminhome/edittours/feedback/reviews/nav"]:::template
end

subgraph "Static Assets (static/)"
direction TB
IndexJS["index.js<br/>(Page behavior)"]:::static
MapJS["map.js<br/>(Google Maps + Fetch polyline + Draw route)"]:::static
CSS["CSS<br/>(style.css, stylesheet.css)"]:::static
end

Browser -->|"GET (HTML) + loads templates"| BaseTpl
Browser -->|"GET (HTML) uses"| VisitorTpls
Browser -->|"GET (HTML) uses"| AdminTpls
Browser -->|"GET (static)"| IndexJS
Browser -->|"GET (static)"| MapJS
Browser -->|"GET (static)"| CSS
end

%% =======================
%% Backend (Monolithic Flask)
%% =======================
subgraph "Backend: Single Flask Service (Python)"
direction TB

FlaskApp["Flask Web App<br/>(app.py)"]:::service

subgraph "HTTP Routes / Controllers"
direction TB
VisitorRoutes["Visitor Page Routes<br/>/  /Tours  /Places  /Contact<br/>/viewTour/&lt;id&gt;  /Tour  /onTour"]:::route
AdminRoutes["Admin Page Routes (Protected)<br/>/adminlogin (GET/POST)<br/>/adminhome /edittours<br/>/adminfeedback /adminreviews"]:::route
PolylineAPI["Polyline/Data API<br/>GET /get_tour_poly/&lt;tour_id&gt;"]:::api
end

subgraph "Auth & Sessions"
direction TB
Auth["Flask-Login<br/>(Admin auth + session cookie)"]:::auth
end

subgraph "Persistence Layer"
direction TB
ORM["Flask-SQLAlchemy ORM<br/>(Models + Queries)"]:::orm
end

subgraph "Polyline/Route Logic"
direction TB
PolylineSvc["Encode polyline from ordered stops<br/>(DB-backed; optional external routing)"]:::logic
end

subgraph "Configuration"
direction TB
EnvCfg[".env / python-dotenv<br/>(MAPS_API_KEY)"]:::config
end

FlaskApp -->|"dispatches"| VisitorRoutes
FlaskApp -->|"dispatches"| AdminRoutes
FlaskApp -->|"dispatches"| PolylineAPI

AdminRoutes -->|"requires session"| Auth
Auth -->|"sets/reads"| FlaskApp

FlaskApp -->|"loads at startup"| EnvCfg

VisitorRoutes -->|"ORM queries"| ORM
AdminRoutes -->|"CRUD + moderation queries"| ORM
PolylineAPI -->|"fetch ordered stops"| ORM
PolylineAPI -->|"builds route geometry"| PolylineSvc
PolylineSvc -->|"reads stops/order"| ORM
end

%% =======================
%% Database
%% =======================
subgraph "Data Store"
direction TB
SQLite["SQLite DB File<br/>(instance/gps-database.sqlite)"]:::db
Tables["Core Tables<br/>tours / places / reviews / tour_places (ordered stops)"]:::dbnote
SQLite -->|"contains"| Tables
end

ORM -->|"SQLAlchemy → SQLite (CRUD)"| SQLite

%% =======================
%% External Services
%% =======================
subgraph "External Services"
direction TB
GoogleMaps["Google Maps Platform<br/>(External)"]:::external
MapsJSAPI["Google Maps JavaScript API<br/>(loaded in browser via MAPS_API_KEY)"]:::external
GoogleWebSvc["Google Maps Web Services (Optional)<br/>(Directions/Geocoding via requests)"]:::externalOptional
GoogleMaps --> MapsJSAPI
GoogleMaps --> GoogleWebSvc
end

%% =======================
%% Main Request Flows
%% =======================
Browser -->|"HTTP GET (HTML): visitor pages"| FlaskApp
Browser -->|"HTTP GET/POST (HTML): admin login + pages"| FlaskApp
Browser -->|"HTTP GET (JSON): /get_tour_poly/<id>"| FlaskApp

MapJS -->|"fetch polyline JSON"| PolylineAPI
Browser -->|"Loads map + tiles"| MapsJSAPI

EnvCfg -->|"inject API key into templates/runtime"| FlaskApp

PolylineSvc -.->|"HTTPS (optional): compute route"| GoogleWebSvc

%% =======================
%% Click Events (mapped components)
%% =======================
click FlaskApp "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/app.py"
click VisitorRoutes "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/app.py"
click AdminRoutes "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/app.py"
click PolylineAPI "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/app.py"
click Auth "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/app.py"
click ORM "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/app.py"
click SQLite "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/instance/gps-database.sqlite"

click BaseTpl "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/base.html"
click VisitorTpls "https://github.com/kmoore1616/gunnison-gps-tour/tree/main/templates/"
click AdminTpls "https://github.com/kmoore1616/gunnison-gps-tour/tree/main/templates/"

click IndexJS "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/static/index.js"
click MapJS "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/static/map.js"
click CSS "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/static/style.css"

%% Additional template file click targets (as separate invisible anchors via nodes)
HomeHtml["home.html"]:::hidden
TourListHtml["tour_list.html"]:::hidden
PlacesHtml["places.html"]:::hidden
ContactHtml["contact.html"]:::hidden
ViewTourHtml["viewTour.html"]:::hidden
OnTourHtml["onTour.html"]:::hidden
VisitorNavHtml["visitornav.html"]:::hidden
AdminLoginHtml["adminlogin.html"]:::hidden
AdminHomeHtml["adminhome.html"]:::hidden
EditToursHtml["edittours.html"]:::hidden
AdminFeedbackHtml["adminfeedback.html"]:::hidden
AdminReviewsHtml["adminreviews.html"]:::hidden
AdminNavHtml["adminnav.html"]:::hidden
StylesheetCss["stylesheet.css"]:::hidden

VisitorTpls --> HomeHtml
VisitorTpls --> TourListHtml
VisitorTpls --> PlacesHtml
VisitorTpls --> ContactHtml
VisitorTpls --> ViewTourHtml
VisitorTpls --> OnTourHtml
VisitorTpls --> VisitorNavHtml
AdminTpls --> AdminLoginHtml
AdminTpls --> AdminHomeHtml
AdminTpls --> EditToursHtml
AdminTpls --> AdminFeedbackHtml
AdminTpls --> AdminReviewsHtml
AdminTpls --> AdminNavHtml
CSS --> StylesheetCss

click HomeHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/home.html"
click TourListHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/tour_list.html"
click PlacesHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/places.html"
click ContactHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/contact.html"
click ViewTourHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/viewTour.html"
click OnTourHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/onTour.html"
click VisitorNavHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/visitornav.html"

click AdminLoginHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/adminlogin.html"
click AdminHomeHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/adminhome.html"
click EditToursHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/edittours.html"
click AdminFeedbackHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/adminfeedback.html"
click AdminReviewsHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/adminreviews.html"
click AdminNavHtml "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/templates/adminnav.html"

click StylesheetCss "https://github.com/kmoore1616/gunnison-gps-tour/blob/main/static/stylesheet.css"

%% =======================
%% Styles
%% =======================
classDef actor fill:#E9F5FF,stroke:#1C6EA4,stroke-width:2px,color:#0B2B40
classDef client fill:#D9ECFF,stroke:#1C6EA4,stroke-width:2px,color:#0B2B40
classDef service fill:#B8DBFF,stroke:#145A86,stroke-width:2px,color:#062033
classDef route fill:#C9EEFF,stroke:#1282A2,stroke-width:2px,color:#053243
classDef api fill:#BFEFFF,stroke:#0A6E8A,stroke-width:2px,color:#053243
classDef auth fill:#D8D0FF,stroke:#5B4BB7,stroke-width:2px,color:#1E144D
classDef orm fill:#D4F7E5,stroke:#1E8E5A,stroke-width:2px,color:#0B3B22
classDef logic fill:#E7F6D5,stroke:#5E8C31,stroke-width:2px,color:#233A10
classDef db fill:#CFF5D2,stroke:#2E7D32,stroke-width:2px,color:#0E2A10
classDef dbnote fill:#E7FFE9,stroke:#2E7D32,stroke-width:1.5px,color:#0E2A10
classDef template fill:#FFF2CC,stroke:#B08900,stroke-width:2px,color:#4A3A00
classDef static fill:#FFE0B2,stroke:#C77700,stroke-width:2px,color:#4A2A00
classDef external fill:#FFD6D6,stroke:#B3261E,stroke-width:2px,color:#4A0C0C
classDef externalOptional fill:#FFE3E3,stroke:#B3261E,stroke-width:2px,color:#4A0C0C,stroke-dasharray: 6 4
classDef config fill:#EEEEEE,stroke:#6E6E6E,stroke-width:2px,color:#222222
classDef hidden fill:#FFFFFF,stroke:#FFFFFF,color:#FFFFFF
```
