# ron-avital29/run_app architecture

> Architecture diagram of the GitHub repository ron-avital29/run_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ron-avital29/run_app
- Repository: https://github.com/ron-avital29/run_app

## Overview

##### Project type and purpose
- This is a full-stack, cross-platform mobile application built with Expo/React Native (using the Expo Router file-based routing conventions).
- It provides runners with AI-generated routes, Google Maps integration, user authentication, route saving/scheduling, and history tracking.
- The backend is comprised of serverless API routes (written in TypeScript) that handle data persistence and orchestrate external services.

##### File structure
- Top-level directories:
- app/ – Expo Router screens and API routes
◦ (root) – main user-flow screens (tabs, choose‐run, run route)
◦ (auth) – sign-in, sign-up, welcome screens
◦ (api) – +api.ts(x) files defining serverless endpoints (add_route, get_route, user, etc.)
◦ +html.tsx, +not-found.tsx, _layout.tsx – global wrappers
- components/ – reusable UI components (Map, RunCard, FormGoogleText, etc.)
- lib/ – business logic utilities (auth helpers, fetch wrapper, circle & line algorithms)
- store/ – global state management (Redux or Zustand)
- constants/, types/ – shared constants and TypeScript types
- config files – babel, metro, tailwind, tsconfig, PostCSS
- Testing: __tests__ covers API, screens, components, lib, store
- Env injection for API keys (.env with Clerk, DB, Google, AI, mapping/weather keys)

##### README for insights
- Tech stack: Expo/React Native, TypeScript, Clerk (auth), Neon (PostgreSQL), Jest, AI-chatbot services, Google Maps, Geoapify, OpenWeather, OpenRouter.
- Features reiterate separation: frontend UI, AI orchestration, data persistence, map rendering.

1. Mobile Client (Expo/React Native)
– Screens: authentication, home, chat, runs, profile, route planning
– UI components library
– State store (store/index.ts)
– Client-side algorithms (circle & line) and fetch wrapper
2. API Layer (serverless functions under app/(api))
– Route management endpoints (add, delete, edit, list)
– User endpoint (auth callback, profile fetch)
– “update_recent”, “toggle_save” functions
3. Database (Neon/PostgreSQL)
– Tables: users, routes, saved_routes, scheduled_routes, recent_routes
4. Authentication Service (Clerk)
– Token issuance, user identity management
5. External Services
– AI Chatbot APIs (6 different endpoints)
– Google Maps API (for client map rendering & geocoding)
– Geoapify / OpenWeather / OpenRouter (weather, routing adjustments)

- Mobile Client → API Layer (HTTPS/JSON) to perform CRUD on routes, fetch user data
- API Layer → Database (SQL queries via Neon client)
- API Layer → Clerk (validate tokens, fetch user profiles)
- API Layer ↔ External AI APIs (HTTP) to generate optimized routes
- Mobile Client → Google Maps SDK (JS/native bridge) to render maps and directions
- Mobile Client ↔ External weather/geocoding services for on-device fetches or via API

c. Architectural patterns & design principles:
- File-system routing (Expo Router) for both UI and API
- Serverless functions for scalability and zero-server-management
- Separation of concerns: UI, business logic (lib), state (store), data access (API)
- Reusable components and theme management (MapThemes, tailwind/nativewind)

d. Key technologies and libraries:
- Expo/React Native & Expo Router
- TypeScript, Jest (testing)
- Clerk (auth), Neon (DB)
- Google Maps SDK, Geoapify, OpenWeather, OpenRouter
- NativeWind (TailwindCSS), Metro bundler, Babel

##### Don’t overthink—be exhaustive in component separation
- Out each directory’s responsibility as a sub-component
- Six AI services, map themes, and utility libraries are visible

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Client Zone
  subgraph "Client (Mobile App)"
    direction TB
    subgraph "Routing & Screens"
      direction TB
      IDX["app/index.tsx"]:::client
      LAYOUT["app/_layout.tsx"]:::client
      HTML["app/+html.tsx"]:::client
      NOTFOUND["app/+not-found.tsx"]:::client
      subgraph "Auth Flow"
        direction TB
        A_LAYOUT["app/(auth)/_layout.tsx"]:::client
        SIGNIN["app/(auth)/sign-in.tsx"]:::client
        SIGNUP["app/(auth)/sign-up.tsx"]:::client
        WELCOME["app/(auth)/wellcome.tsx"]:::client
      end
      subgraph "Tab Navigation"
        direction TB
        TABLAYOUT["app/(root)/(tabs)/_layout.tsx"]:::client
        CHAT["app/(root)/(tabs)/chat.tsx"]:::client
        HOME["app/(root)/(tabs)/home.tsx"]:::client
        PROFILE["app/(root)/(tabs)/profile.tsx"]:::client
        RUNS["app/(root)/(tabs)/runs.tsx"]:::client
      end
      CHOOSE["app/(root)/choose-run.tsx"]:::client
      RUNAROUTE["app/(root)/run-a-route.tsx"]:::client
    end
    subgraph "UI Components Library"
      direction TB
      ABOUT["components/AboutModal.tsx"]:::client
      AITHINK["components/AiThinking.tsx"]:::client
      ALERT["components/CustomAlert.tsx"]:::client
      BUTTON["components/CustomButton.tsx"]:::client
      FORMGT["components/FormGoogleText.tsx"]:::client
      GTXT["components/GoogleTextInput.tsx"]:::client
      HHELP["components/HadasHelp.tsx"]:::client
      HINP["components/HadasInp.tsx"]:::client
      INPUT["components/InputField.tsx"]:::client
      MAPCP["components/Map.tsx"]:::client
      DATEP["components/MyDatePicker.tsx"]:::client
      OAUTH["components/OAuth.tsx"]:::client
      RUNCARD["components/RunCard.tsx"]:::client
      RUNLAYOUT["components/RunLayout.tsx"]:::client
      SPINNER["components/Spinner.tsx"]:::client
      subgraph "Map Themes"
        direction TB
        MTJS["components/MapThemes/mapThemes.jsx"]:::client
        MTJSON["components/MapThemes/*.json"]:::client
      end
    end
    subgraph "State & Utils"
      direction TB
      STORE["store/index.ts"]:::client
      AUTHUTIL["lib/auth.ts"]:::client
      FETCHWRAP["lib/fetch.ts"]:::client
      CIRCLE["lib/circle_algorithm.tsx"]:::client
      LINE["lib/line_algorithm.tsx"]:::client
      UTILS["lib/utils.ts"]:::client
    end
  end

  %% Backend Zone
  subgraph "Serverless Backend (API)"
    direction TB
    subgraph "Route Management Endpoints"
      direction TB
      ADD["add_route+api.ts"]:::backend
      DELETE["delete_route+api.tsx"]:::backend
      EDITSCHEDULE["edit_schedule_route+api.tsx"]:::backend
      EDITTITLE["edit_title_route+api.tsx"]:::backend
      FUTURE["future_routes+api.ts"]:::backend
      GET["get_route+api.ts"]:::backend
      RECENT["recent_routes+api.ts"]:::backend
      SAVED["saved_routes+api.ts"]:::backend
      TOGGLE["toggle_save_route+api.tsx"]:::backend
      UPDREC["update_recent+api.ts"]:::backend
      UPDSAVED["update_route_saved+api.tsx"]:::backend
      UPDSCHED["update_route_scheduled+api.tsx"]:::backend
    end
    USER["user+api.ts"]:::backend
  end

  %% External Services
  subgraph "External Services"
    direction TB
    DB[(Neon/PostgreSQL)]:::external
    CLERK[Clerk Auth Service]:::external
    subgraph "AI Chatbot APIs"
      direction TB
      AI1["AI Endpoint 1"]:::external
      AI2["AI Endpoint 2"]:::external
      AI3["AI Endpoint 3"]:::external
      AI4["AI Endpoint 4"]:::external
      AI5["AI Endpoint 5"]:::external
      AI6["AI Endpoint 6"]:::external
    end
    GMAPS[Google Maps SDK]:::external
    GEO[Geoapify/OpenWeather/OpenRouter]:::external
  end

  %% Connections
  %% Client to Backend
  MAPCP -->|fetch JSON| GET
  IDX -->|navigate| LAYOUT
  IDX -->|navigate| HTML
  IDX -->|navigate| NOTFOUND
  CHAT -->|fetch routes| GET
  HOME -->|fetch user| USER
  RUNS -->|list saved| SAVED
  CHOOSE -->|add route| ADD
  RUNAROUTE -->|update recent| UPDREC

  %% Backend to DB and Auth
  ADD -->|SQL query| DB
  DELETE -->|SQL query| DB
  EDITSCHEDULE -->|SQL query| DB
  EDITTITLE -->|SQL query| DB
  FUTURE -->|SQL query| DB
  GET -->|SQL query| DB
  RECENT -->|SQL query| DB
  SAVED -->|SQL query| DB
  TOGGLE -->|SQL query| DB
  UPDREC -->|SQL query| DB
  UPDSAVED -->|SQL query| DB
  UPDSCHED -->|SQL query| DB
  USER -->|validate token| CLERK

  %% Backend to AI
  ADD -->|"generate route"| AI1
  EDITSCHEDULE -->|"adjust via AI"| AI2
  GET -->|"AI details"| AI3
  UPDSCHED -->|"AI adjustment"| AI4

  %% Client to External
  MAPCP -->|render| GMAPS
  HOME -->|geocode| GEO
  RUNAROUTE -->|weather| GEO

  %% Click Events
  click IDX "https://github.com/ron-avital29/run_app/blob/master/app/index.tsx"
  click LAYOUT "https://github.com/ron-avital29/run_app/blob/master/app/_layout.tsx"
  click HTML "https://github.com/ron-avital29/run_app/blob/master/app/+html.tsx"
  click NOTFOUND "https://github.com/ron-avital29/run_app/blob/master/app/+not-found.tsx"
  click A_LAYOUT "https://github.com/ron-avital29/run_app/blob/master/app/(auth)/_layout.tsx"
  click SIGNIN "https://github.com/ron-avital29/run_app/blob/master/app/(auth)/sign-in.tsx"
  click SIGNUP "https://github.com/ron-avital29/run_app/blob/master/app/(auth)/sign-up.tsx"
  click WELCOME "https://github.com/ron-avital29/run_app/blob/master/app/(auth)/wellcome.tsx"
  click TABLAYOUT "https://github.com/ron-avital29/run_app/blob/master/app/(root)/(tabs)/_layout.tsx"
  click CHAT "https://github.com/ron-avital29/run_app/blob/master/app/(root)/(tabs)/chat.tsx"
  click HOME "https://github.com/ron-avital29/run_app/blob/master/app/(root)/(tabs)/home.tsx"
  click PROFILE "https://github.com/ron-avital29/run_app/blob/master/app/(root)/(tabs)/profile.tsx"
  click RUNS "https://github.com/ron-avital29/run_app/blob/master/app/(root)/(tabs)/runs.tsx"
  click CHOOSE "https://github.com/ron-avital29/run_app/blob/master/app/(root)/choose-run.tsx"
  click RUNAROUTE "https://github.com/ron-avital29/run_app/blob/master/app/(root)/run-a-route.tsx"
  click ABOUT "https://github.com/ron-avital29/run_app/blob/master/components/AboutModal.tsx"
  click AITHINK "https://github.com/ron-avital29/run_app/blob/master/components/AiThinking.tsx"
  click ALERT "https://github.com/ron-avital29/run_app/blob/master/components/CustomAlert.tsx"
  click BUTTON "https://github.com/ron-avital29/run_app/blob/master/components/CustomButton.tsx"
  click FORMGT "https://github.com/ron-avital29/run_app/blob/master/components/FormGoogleText.tsx"
  click GTXT "https://github.com/ron-avital29/run_app/blob/master/components/GoogleTextInput.tsx"
  click HHELP "https://github.com/ron-avital29/run_app/blob/master/components/HadasHelp.tsx"
  click HINP "https://github.com/ron-avital29/run_app/blob/master/components/HadasInp.tsx"
  click INPUT "https://github.com/ron-avital29/run_app/blob/master/components/InputField.tsx"
  click MAPCP "https://github.com/ron-avital29/run_app/blob/master/components/Map.tsx"
  click DATEP "https://github.com/ron-avital29/run_app/blob/master/components/MyDatePicker.tsx"
  click OAUTH "https://github.com/ron-avital29/run_app/blob/master/components/OAuth.tsx"
  click RUNCARD "https://github.com/ron-avital29/run_app/blob/master/components/RunCard.tsx"
  click RUNLAYOUT "https://github.com/ron-avital29/run_app/blob/master/components/RunLayout.tsx"
  click SPINNER "https://github.com/ron-avital29/run_app/blob/master/components/Spinner.tsx"
  click MTJS "https://github.com/ron-avital29/run_app/blob/master/components/MapThemes/mapThemes.jsx"
  click STORE "https://github.com/ron-avital29/run_app/blob/master/store/index.ts"
  click AUTHUTIL "https://github.com/ron-avital29/run_app/blob/master/lib/auth.ts"
  click FETCHWRAP "https://github.com/ron-avital29/run_app/blob/master/lib/fetch.ts"
  click CIRCLE "https://github.com/ron-avital29/run_app/blob/master/lib/circle_algorithm.tsx"
  click LINE "https://github.com/ron-avital29/run_app/blob/master/lib/line_algorithm.tsx"
  click UTILS "https://github.com/ron-avital29/run_app/blob/master/lib/utils.ts"
  click ADD "https://github.com/ron-avital29/run_app/blob/master/app/(api)/add_route+api.ts"
  click DELETE "https://github.com/ron-avital29/run_app/blob/master/app/(api)/delete_route+api.tsx"
  click EDITSCHEDULE "https://github.com/ron-avital29/run_app/blob/master/app/(api)/edit_schedule_route+api.tsx"
  click EDITTITLE "https://github.com/ron-avital29/run_app/blob/master/app/(api)/edit_title_route+api.tsx"
  click FUTURE "https://github.com/ron-avital29/run_app/blob/master/app/(api)/future_routes+api.ts"
  click GET "https://github.com/ron-avital29/run_app/blob/master/app/(api)/get_route+api.ts"
  click RECENT "https://github.com/ron-avital29/run_app/blob/master/app/(api)/recent_routes+api.ts"
  click SAVED "https://github.com/ron-avital29/run_app/blob/master/app/(api)/saved_routes+api.ts"
  click TOGGLE "https://github.com/ron-avital29/run_app/blob/master/app/(api)/toggle_save_route+api.tsx"
  click UPDREC "https://github.com/ron-avital29/run_app/blob/master/app/(api)/update_recent+api.ts"
  click UPDSAVED "https://github.com/ron-avital29/run_app/blob/master/app/(api)/update_route_saved+api.tsx"
  click UPDSCHED "https://github.com/ron-avital29/run_app/blob/master/app/(api)/update_route_scheduled+api.tsx"
  click USER "https://github.com/ron-avital29/run_app/blob/master/app/(api)/user+api.ts"

  %% Styles
  classDef client fill:#e0f7fa,stroke:#006064,color:#006064
  classDef backend fill:#e3f2fd,stroke:#0d47a1,color:#0d47a1
  classDef external fill:#fff3e0,stroke:#e65100,color:#e65100
```
