Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/jhonyes04/new-wayfy/llms.txt

Use this file to discover all available pages before exploring further.

WayFy is organised as a single monorepo with two top-level workspaces: frontend/ for the React 18 + Vite application, and backend/ for the Python Flask API. In production the Flask server compiles and serves the Vite build directly from ../dist/ so the whole platform ships as one deployable unit. During development the two processes run independently — Vite on port 3000 and Flask on port 3001 — and communicate through a proxied fetch using the VITE_BACKEND_URL environment variable.

​
Monorepo Structure

new-wayfy/
├── frontend/           # React 18 + Vite SPA
│   ├── src/
│   │   ├── pages/      # Thin route-level wrappers
│   │   ├── modules/    # Self-contained feature units
│   │   ├── components/ # Shared primitives
│   │   ├── hooks/      # Shared custom hooks
│   │   ├── services/   # API utilities and third-party wrappers
│   │   └── context/    # Auth + global store providers
│   └── dist/           # Production build (served by Flask)
├── backend/
│   └── src/
│       ├── app.py      # Flask application factory
│       └── api/
│           ├── routes/       # HTTP layer
│           ├── controllers/  # Business logic
│           ├── models/       # SQLAlchemy ORM
│           └── utils.py      # APIException, Flask-Limiter
└── Pipfile             # Stub — real deps live in backend/Pipfile

​
Request Flow

Every user interaction follows one of two paths depending on whether it requires server data or can be handled client-side. 
Browser
  │
  ├─[static assets]─► Flask (production) or Vite dev server
  │
  └─[API call]──────► Flask /api/<blueprint>
                          │
                          ├─ JWT verification (Flask-JWT-Extended)
                          ├─ Rate limiting (Flask-Limiter)
                          │
                          ├─► Controller (business logic)
                          │       │
                          │       ├─► PostgreSQL via SQLAlchemy
                          │       ├─► Cloudinary (image uploads)
                          │       └─► Groq / Llama (AI queries)
                          │
                          └─► JSON response → React state update
Map data follows a separate path: the browser calls OSM Overpass and Geoapify directly from the AccessibilityMap module. The Flask backend is never in the hot path for map tile or POI requests, keeping map latency low.

​
External Services

Mapbox GL / React Map GL

Renders the interactive wheelchair-accessibility map. Four registered layer IDs: clusters, unclustered-point (OSM data via Geoapify), community-approved, and community-pending (community pins from /api/places).

Geoapify & OSM Overpass

Provides POI data tagged with wheelchair accessibility from OpenStreetMap. The frontend queries Geoapify’s geocoder autocomplete and Overpass for place features displayed on the map.

Groq / Llama AI

Powers the AI assistant via /api/ai. Prompts are rate-limited to 20 requests per minute per IP. The backend holds the GROQ_API_KEY and proxies all LLM calls, keeping credentials server-side.

Cloudinary

Stores user avatars, accessibility review photos, and trip cover images. The backend uploads to Cloudinary and persists only the filename or public ID in PostgreSQL. Static files are served through Flask endpoints under /api/users/avatar/, /api/accessibility/photos/, and /api/trips/cover/.

PostgreSQL + SQLAlchemy

Primary datastore. Managed via Flask-Migrate (Alembic under the hood). The DATABASE_URL env var is auto-corrected from the legacy postgres:// scheme to postgresql:// on startup.

Nominatim / Geoapify Geocoding

Used by the AI controller (/api/ai/geocode and /api/ai/geocode-poi) to resolve natural-language place names to coordinates, enabling the AI assistant to pan the map to locations it suggests.

​
Deployment Topology

1

Build the frontend

Run npm run build inside frontend/. Vite outputs compiled assets to frontend/dist/.
2

Configure environment variables

Set DATABASE_URL, JWT_SECRET_KEY, GROQ_API_KEY, CLOUDINARY_*, and CORS_ALLOWED_ORIGINS on the server. JWT_SECRET_KEY is required — Flask raises a RuntimeError at startup if it is missing.
3

Start the Flask server

Run gunicorn from backend/src/. Flask detects ENV == "production" (when FLASK_DEBUG is not "1") and serves index.html from ../dist/ for all non-API routes, enabling client-side routing to work without a separate static server.
4

Database migrations

Apply pending Alembic migrations with pipenv run upgrade before or after each deploy. Schema changes are authored with pipenv run migrate, which auto-generates a versioned migration file in backend/migrations/.
In development, set FLASK_DEBUG=1 to activate the auto-reloading Flask dev server and the Vite dev server independently. The Flask root route (/) renders a live sitemap of all registered API endpoints instead of serving the SPA.

​
Architecture Pages

Frontend Architecture

Module layout, React contexts, routing with lazy loading, shared hooks, API utility pattern, and styling conventions.

Backend Architecture

Three-layer route → controller → model design, Flask app initialisation, all route blueprints, error handling, and static file serving.

Build docs developers (and LLMs) love

Get started for freeTalk to us