# beastofshadow/mobishare architecture

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

- Interactive diagram: https://gitdiagram.com/beastofshadow/mobishare
- Repository: https://github.com/beastofshadow/mobishare

## Overview

##### Project type and purpose
- This is a full-stack web application (monolithic ASP NET Core Razor Pages) with a layered architecture.
- Purpose: “Mobishare” is an urban mobility platform that allows users to locate, reserve, and ride standard bikes, e-bikes, and scooters. It provides real-time map updates, telemetry via MQTT, chat support, payments via PayPal, and Google OAuth authentication.

##### File structure
- Top-level solution contains four main projects:
- Mobishare.App – the ASP NET Core Razor Pages web application (UI + Web API endpoints + SignalR hubs + hosted services).
- Mobishare.Core – domain models, EF Core DbContext, request/response DTOs (CQRS style), validation attributes, security policies.
- Mobishare.Infrastructure – implementations of external-facing services (Google geocoding, AI chatbot, MQTT, SignalR hubs).
- PayPal.REST – a wrapper for PayPal REST APIs.
- Mobishare.Tests – automated tests.
- Web UI: Razor Pages under Areas/Admin, Areas/Identity, and /Pages. Static assets under wwwroot (CSS, JS, Bootstrap, jQuery).
- Configuration: appsettings.json, launchSettings.json, environment variables for OAuth, API keys, PayPal.
- Data: EF Core migrations under Core/Migrations, using SQLite.
- Real-time & messaging: SignalR hubs (ChatHub, VehicleHub, TimerHub) and MQTT hosted services.

##### README
- Confirms tech stack: Razor Pages, ASP NET Core, SQLite, SignalR, OAuth, PayPal, MQTT, Google Maps, AWS.
- Describes user/admin flows and required environment variables.

##### Detail & essential elements
- Don’t simply list files; capture logical components: UI, API, business logic, data, and integrations.
- How data flows end-to-end: from user click → server handler → database → back to user / SignalR client.
- Hosted services polling MQTT and pushing updates to hubs.
- Environment/configuration boundary for keys and secrets.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client" 
        direction TB
        RazorPages["Razor Pages UI"]:::frontend
        StaticAssets["Static Assets (wwwroot)"]:::frontend
    end

    %% Server Boundary
    subgraph "Mobishare.App (Web Server)" 
        direction TB
        Program["Program.cs"]:::server
        subgraph "Presentation & API"
            direction TB
            RazorEndpoints["Razor Page Handlers"]:::server
            SignalRHubGroup["SignalR Hubs"]:::server
            ChatHub["ChatHub"]:::server
            VehicleHub["VehicleHub"]:::server
            TimerHub["TimerHub"]:::server
        end
        subgraph "Hosted Services"
            direction TB
            MqttHosted["MqttHostedService"]:::server
            TimerHosted["TimerService"]:::server
        end
    end

    %% Core Layer
    subgraph "Mobishare.Core (Domain & Application)" 
        direction TB
        AppDbContext["ApplicationDbContext"]:::core
        DomainModels["Domain Models"]:::core
        Requests["CQRS Requests"]:::core
        GeocodeSvc["IGoogleGeocodingService"]:::core
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Migrations["EF Core Migrations"]:::db
        SQLiteDB["SQLite Database"]:::db
    end

    %% Infrastructure Layer
    subgraph "Mobishare.Infrastructure" 
        direction TB
        subgraph "SignalR Implementations"
            ChatHubImpl["ChatHub.cs"]:::infra
            VehicleHubImpl["VehicleHub.cs"]:::infra
            TimerHubImpl["TimerHub.cs"]:::infra
        end
        subgraph "MQTT Services"
            MqttHandler["MqttMessageHandler"]:::infra
            MqttReceiver["MqttReceiver"]:::infra
        end
        subgraph "HostedServices"
            MqttHostedSvcImpl["MqttHostedService.cs"]:::infra
            TimerSvcImpl["TimerService.cs"]:::infra
        end
        subgraph "ChatBot AI"
            Ollama["OllamaService"]:::infra
            Embedding["EmbeddingService"]:::infra
            KBRetrieve["KnowledgeBaseRetriever"]:::infra
        end
    end

    %% PayPal Integration
    subgraph "PayPal.REST" 
        direction TB
        PayPalClient["PayPalClient.cs"]:::external
        IPayPalClient["IPayPalClient.cs"]:::external
        PayPalModels["Models"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleOAuth["Google OAuth"]:::external
        GoogleMaps["Google Maps API"]:::external
        MQTTBroker["MQTT Broker"]:::external
        AWS["AWS Infrastructure"]:::external
    end

    %% Connections
    RazorPages -->|"HTTP/JS"| RazorEndpoints
    StaticAssets --> RazorEndpoints
    RazorEndpoints -->|calls| Program
    Program -->|DI| GeocodeSvc
    Program -->|DI| ChatHub
    Program -->|DI| VehicleHub
    Program -->|DI| TimerHub
    Program -->|runs| MqttHosted
    Program -->|runs| TimerHosted
    RazorEndpoints -->|invoke| AppDbContext
    AppDbContext -->|reads/writes| SQLiteDB
    AppDbContext -->|migrations| Migrations
    GeocodeSvc -->|calls| GoogleMaps
    MqttHosted -->|subscribe/publish| MQTTBroker
    MQTTBroker -->|forwards| MqttHandler
    MqttHandler -->|push| ChatHub
    MqttHandler -->|push| VehicleHub
    MqttHandler -->|push| TimerHub
    ChatHub --> RazorPages
    VehicleHub --> RazorPages
    TimerHub --> RazorPages
    Program -->|auth| GoogleOAuth
    Program -->|payment| PayPalClient
    PayPalClient -->|calls| PayPal.REST
    AWS --> Program

    %% Click Events
    click Program "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.App/Program.cs"
    click RazorPages "https://github.com/beastofshadow/mobishare/tree/main/Mobishare.App/Pages/"
    click StaticAssets "https://github.com/beastofshadow/mobishare/tree/main/Mobishare.App/wwwroot/"
    click AppDbContext "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Core/Data/ApplicationDbContext.cs"
    click DomainModels "https://github.com/beastofshadow/mobishare/tree/main/Mobishare.Core/Models/"
    click Requests "https://github.com/beastofshadow/mobishare/tree/main/Mobishare.Core/Requests/"
    click GeocodeSvc "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Core/Services/GoogleGeocoding/IGoogleGeocodingService.cs"
    click Migrations "https://github.com/beastofshadow/mobishare/tree/main/Mobishare.Core/Migrations/"
    click ChatHub "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/SignalR/ChatHub.cs"
    click VehicleHub "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/SignalR/VehicleHub.cs"
    click TimerHub "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/SignalR/TimerHub.cs"
    click MqttHosted "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/HostedServices/MqttHostedService.cs"
    click TimerHosted "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/HostedServices/TimerService.cs"
    click MqttHandler "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/Mqtt/MqttMessageHandler.cs"
    click MqttReceiver "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/Mqtt/MqttReceiver.cs"
    click Ollama "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/ChatBotAIService/OllamaService.cs"
    click Embedding "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/ChatBotAIService/EmbeddingService.cs"
    click KBRetrieve "https://github.com/beastofshadow/mobishare/blob/main/Mobishare.Infrastructure/Services/ChatBotAIService/KnowledgeBaseRetriever.cs"
    click PayPalClient "https://github.com/beastofshadow/mobishare/blob/main/PayPal.REST/Client/PayPalClient.cs"
    click IPayPalClient "https://github.com/beastofshadow/mobishare/blob/main/PayPal.REST/Client/IPayPalClient.cs"
    click PayPalModels "https://github.com/beastofshadow/mobishare/tree/main/PayPal.REST/Models/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef server fill:#F2F2F2,stroke:#666666,color:#333333
    classDef core fill:#FFEFD5,stroke:#FF8C00,color:#FF8C00
    classDef infra fill:#E6FFE6,stroke:#2E8B57,color:#2E8B57
    classDef external fill:#E0FFE0,stroke:#228B22,color:#228B22
    classDef db fill:#FFF0F5,stroke:#C71585,color:#C71585,stroke-dasharray: 5 5
```
