# kevinq989/neighbourly architecture

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

- Interactive diagram: https://gitdiagram.com/kevinq989/neighbourly
- Repository: https://github.com/kevinq989/neighbourly

## Overview

##### Project Type and Purpose
- This is a native iOS application (built in SwiftUI) that uses MVVM patterns on the client and Supabase (cloud-hosted Postgres + Auth + Realtime) as its backend.
- Purpose: allow users to register, post help requests, match on proximity/skills, chat, rate each other, and receive notifications.

##### File Structure
- Top-level: Xcode project (`Neighbourly.xcodeproj`), app source in `Neighbourly/Neighbourly`, unit/UI tests, README, screenshots.
- In `Neighbourly/Neighbourly`:
– SwiftUI Views: `AuthView.swift`, `HomePageView.swift`, `ChatView.swift`, etc.
– ViewModels: e.g. `ChatDetailViewModel.swift`.
– Services/Data Layer: `Supabase.swift`, `DataFetching.swift`, `LocationManager.swift`.
– Models: `Models.swift`.
- No custom backend code here: all server logic is in Supabase; client communicates via REST/Realtime.

##### Key Insights from README
- Features: Authentication, Posting Requests, Optimized Matching, Rating System, Real-time Notifications.
- Technical Stack: SwiftUI (UI), Combine/async (network), Supabase (Auth, Database, Realtime), CoreLocation (location), APNs (push notifications).

##### Main Components
a. iOS Client (Mobile App)
- UI Layer: SwiftUI Views
- Presentation / Business Logic Layer: ViewModels + Models (MVVM)
- Data Layer: SupabaseService (in Supabase.swift), DataFetching, LocationManager
b. External Services
- Supabase
- Auth service
- Database (PostgreSQL)
- Realtime subscriptions
- CoreLocation (iOS framework)
- APNs (Apple Push Notification Service)
c. (Optional) Dependency injection or shared utilities if used (e.g., any extensions in View+Extensions.swift).

##### Relationships & Data Flows
1. User taps UI → SwiftUI View → invokes ViewModel.
2. ViewModel calls Data Layer (SupabaseService or DataFetching).
3. Data Layer issues HTTPS requests / Realtime subscriptions to Supabase.
4. Supabase Auth returns JWT/user profile → Data Layer → ViewModel → View (updates UI).
5. Supabase Database returns request listings, matches, chat messages.
6. Realtime events (new messages, new requests) push via WebSocket → Data Layer → ViewModel → View.
7. LocationManager fetches GPS → ViewModel (to include location in requests or matching).
8. For push notifications: Supabase triggers events → APNs → iOS App.

##### Architectural Patterns & Principles
- MVVM: isolate UI code (Views) from business logic (ViewModels) and data access (Services).
- Single Responsibility: each service class handles one concern (e.g., SupabaseService for network, LocationManager for GPS).
- Reactive updates: async/await or Combine for real-time and REST responses.

a. “UI Layer (SwiftUI Views)”
b. “Presentation Layer (ViewModels + Models)”
c. “Data Layer (SupabaseService, DataFetching, LocationManager)”
- Auth Service
- Database (PostgreSQL)
- Realtime Service
4. Above the “iOS Client,” place “CoreLocation Framework.”
5. Connect:
6. Component with the main file(s) responsible:
- UI Layer: e.g., `HomePageView.swift`, `ChatView.swift`, etc.
- ViewModels: `ChatDetailViewModel.swift`
- Data Layer: `Supabase.swift`, `DataFetching.swift`, `LocationManager.swift`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "iOS Client"
        subgraph "UI Layer (SwiftUI Views)"
            AuthView["AuthView"]:::ui
            HomePageView["HomePageView"]:::ui
            ChatView["ChatView"]:::ui
            ChatDetailView["ChatDetailView"]:::ui
            EditProfileView["EditProfileView"]:::ui
            LeaveReviewView["LeaveReviewView"]:::ui
            NewRequestView["NewRequestView"]:::ui
            ProfileView["ProfileView"]:::ui
            RequestDetailView["RequestDetailView"]:::ui
            TabBarView["TabBarView"]:::ui
        end
        subgraph "Presentation Layer (ViewModels + Models)"
            ChatDetailViewModel["ChatDetailViewModel"]:::pres
            Models["Models"]:::pres
        end
        subgraph "Data Layer (Services)"
            SupabaseService["SupabaseService"]:::data
            DataFetching["DataFetching"]:::data
            LocationManager["LocationManager"]:::data
            ViewExtensions["View+Extensions"]:::data
        end
        NeighbourlyApp["NeighbourlyApp"]:::ui
        Assets["Assets.xcassets\nPreviewAssets"]:::data
    end

    CoreLocation["CoreLocation Framework"]:::ext
    SupabaseAuth["Supabase Auth"]:::ext
    SupabaseDB["Supabase Database"]:::ext
    SupabaseRealtime["Supabase Realtime"]:::ext
    APNs["APNs"]:::ext

    %% UI to Presentation
    AuthView -->|userAction| ChatDetailViewModel
    HomePageView -->|userAction| ChatDetailViewModel
    ChatView -->|userAction| ChatDetailViewModel
    ChatDetailView -->|userAction| ChatDetailViewModel
    EditProfileView -->|userAction| ChatDetailViewModel
    LeaveReviewView -->|userAction| ChatDetailViewModel
    NewRequestView -->|userAction| ChatDetailViewModel
    ProfileView -->|userAction| ChatDetailViewModel
    RequestDetailView -->|userAction| ChatDetailViewModel
    TabBarView -->|userAction| ChatDetailViewModel
    NeighbourlyApp -->|launch| HomePageView

    %% Presentation to Data
    ChatDetailViewModel -->|call| SupabaseService
    Models -->|dataModel| SupabaseService

    %% Location and CoreLocation
    CoreLocation -->|GPS data| LocationManager
    LocationManager -->|locationUpdate| ChatDetailViewModel

    %% Data Layer to Supabase
    SupabaseService -->|HTTP POST /login| SupabaseAuth
    SupabaseService -->|HTTP GET/POST| SupabaseDB
    SupabaseService -->|subscribe to channels| SupabaseRealtime
    SupabaseRealtime -.->|realtimeUpdate| SupabaseService
    SupabaseService -->|push to APNs| APNs

    %% Realtime to Presentation
    SupabaseService -->|realtime messages| ChatDetailViewModel

    %% Styles
    classDef ui fill:#e0f7fa,stroke:#0288d1,color:#000
    classDef pres fill:#e8f5e9,stroke:#2e7d32,color:#000
    classDef data fill:#ffe0b2,stroke:#ef6c00,color:#000
    classDef ext fill:#eceff1,stroke:#546e7a,color:#000

    %% Click Events
    click AuthView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/AuthView.swift"
    click HomePageView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/HomePageView.swift"
    click ChatView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/ChatView.swift"
    click ChatDetailView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/ChatDetailView.swift"
    click EditProfileView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/EditProfileView.swift"
    click LeaveReviewView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/LeaveReviewView.swift"
    click NewRequestView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/NewRequestView.swift"
    click ProfileView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/ProfileView.swift"
    click RequestDetailView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/RequestDetailView.swift"
    click TabBarView "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/TabBarView.swift"
    click NeighbourlyApp "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/NeighbourlyApp.swift"
    click ChatDetailViewModel "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/ChatDetailViewModel.swift"
    click Models "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/Models.swift"
    click SupabaseService "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/Supabase.swift"
    click DataFetching "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/DataFetching.swift"
    click LocationManager "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/LocationManager.swift"
    click ViewExtensions "https://github.com/kevinq989/neighbourly/blob/main/Neighbourly/Neighbourly/View+Extensions.swift"
    click Assets "https://github.com/kevinq989/neighbourly/tree/main/Neighbourly/Neighbourly/Assets.xcassets/"
```
