# 390minicapstone/polaris architecture

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

- Interactive diagram: https://gitdiagram.com/390minicapstone/polaris
- Repository: https://github.com/390minicapstone/polaris

## Overview

##### Project Type and Purpose
- This is a cross‑platform mobile application built with React Native (Expo) that provides campus map/navigation functionality, integrates with Google Calendar/Maps, and uses Firebase for user authentication and data storage.
- Key indicators: a single “Polaris‑FE” directory containing Expo‑specific config (app.config.js, metro.config.cjs), React components/hooks/contexts, and Firebase config.

##### File Structure
- app/ & components/ & hooks/ & contexts/ & services/ – the core of your client‑side architecture
- firebase/firebaseConfig.ts – BaaS configuration
- services/googleCalendarService.ts, googleMapsRoutes.ts, firestoreService.ts – external API integrations
- tests under __tests__, jest‑setup.ts – automated testing
- assets/, constants/, utils/ – static data and helper code

##### README and Docs
- The README is minimal; check docs/frontend for installation and E2E procedures. There’s no internal “backend” code – the app relies on Firebase (Auth+Firestore) and Google APIs.

a. Main Components
1) Mobile Client (React Native App)
– UI Layer: Screens & Navigation (expo‑router, app/(tabs), components/*)
– State Management: React Contexts (AuthContext, BuildingContext, NavigationContext, ThemeContext)
– Domain Logic: Hooks (useGoogleAuth, useNextClassTimer, useMapLocation)
– Service Layer: services/firestoreService, googleCalendarService, googleMapsRoutes
– Utilities & Constants: utils/, constants/
2) External Services
– Firebase Auth (user login, token management)
– Firestore Database (building data, user preferences)
– Google Calendar API
– Google Maps Routes API
3) Testing & CI/CD (optional to show)
– Jest/unit tests
– GitHub Actions (polaris.yml)

b. Relationships & Data Flows
- UI triggers Context or Hook → Hook calls Service → Service issues HTTP/gRPC request to external API → Response flows back to Hook → Context updates → UI re‑renders
- Auth flows: UI → AuthContext → Firebase Auth → return JWT → stored via authStorage → subsequent calls to Firestore/Google APIs
- Navigation flows: User selects destination in UI → NavigationContext → googleMapsRoutes → Map component draws polyline

c. Architectural Patterns & Principles
– Component‑based UI (small, reusable React components)
– Separation of concerns:
- UI vs. State (Contexts) vs. Data‑access (Services) vs. Side‑effects (Hooks)
– Dependency injection via Context Providers
– Single source of static data via constants/ and utils/
– Test‑driven development (extensive __tests__ directories)

d. Key Technologies & Frameworks
– React Native & Expo (app.config.js, metro.config.cjs)
– React Context API & Hooks
– Firebase (Auth + Firestore)
– Google Calendar & Maps REST APIs
– Jest & Testing Library
– GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Mobile App"
        subgraph "UI Layer"
            bottomSheet["BottomSheetComponent"]:::ui
            buildingsUI["Buildings"]:::ui
            floorSelector["FloorSelector"]:::ui
            placesInput["GooglePlacesInput"]:::ui
            mapComponent["Map"]:::ui
            mapButtons["MapButtons"]:::ui
            navigationUI["Navigation"]:::ui
            nextClassCard["NextClassComponent"]:::ui
            pois["POIs"]:::ui
            pinchPan["PinchPanContainer"]:::ui
            sharedUI["Shared UI Elements"]:::ui
            themedText["ThemedText"]:::ui
            themedView["ThemedView"]:::ui
        end

        subgraph "State Management"
            authContext["AuthContext"]:::state
            buildingContext["BuildingContext"]:::state
            navigationContext["NavigationContext"]:::state
            themeContext["ThemeContext"]:::state
            globalProvider["GlobalContextProvider"]:::state
        end

        subgraph "Domain Logic Hooks"
            googleAuth["useGoogleAuth"]:::service
            googleCalendar["useGoogleCalendar"]:::service
            selectedCalendar["useSelectedCalendar"]:::service
            nextEvent["useGoogleNextEvent"]:::service
            mapLocation["useMapLocation"]:::service
            mapsRoute["useGoogleMapsRoute"]:::service
            classTimer["useNextClassTimer"]:::service
        end

        subgraph "Service Layer"
            firestoreSvc["firestoreService"]:::service
            gCalSvc["googleCalendarService"]:::service
            gMapsSvc["googleMapsRoutes"]:::service
        end

        subgraph "Utilities & Config"
            constants["Constants"]:::service
            utils["Utilities"]:::service
            firebaseCfg["FirebaseConfig"]:::service
            expoCfg["ExpoConfig"]:::service
        end
    end

    subgraph "External Services"
        firebaseAuth["Firebase Auth"]:::external
        firestoreDB["Firestore DB"]:::external
        googleCalendarAPI["Google Calendar API"]:::external
        googleMapsAPI["Google Maps Routes API"]:::external
    end

    %% Data Flows
    bottomSheet -->|uses| googleAuth
    buildingsUI -->|reads| buildingContext
    floorSelector -->|reads| buildingContext
    placesInput -->|uses| mapLocation
    mapComponent -->|uses| mapsRoute
    mapButtons -->|triggers| mapsRoute
    navigationUI -->|reads| navigationContext
    nextClassCard -->|uses| nextEvent
    pois -->|uses| mapLocation
    pinchPan -->|wraps| mapComponent
    sharedUI -->|used by| bottomSheet
    themedText -->|wraps| sharedUI
    themedView -->|wraps| sharedUI

    authContext -->|provides| googleAuth
    buildingContext -->|provides| mapLocation
    navigationContext -->|provides| mapsRoute
    themeContext -->|provides| themedText
    themeContext -->|provides| themedView
    globalProvider -->|combines| authContext
    globalProvider -->|combines| buildingContext
    globalProvider -->|combines| navigationContext
    globalProvider -->|combines| themeContext

    googleAuth -->|calls| gCalSvc
    googleCalendar -->|calls| gCalSvc
    selectedCalendar -->|calls| gCalSvc
    nextEvent -->|calls| gCalSvc
    mapLocation -->|calls| gMapsSvc
    mapsRoute -->|calls| gMapsSvc
    classTimer -->|depends on| nextEvent

    firestoreSvc -->|requests| firestoreDB
    gCalSvc -->|requests| googleCalendarAPI
    gMapsSvc -->|requests| googleMapsAPI
    firebaseAuth -->|authenticates| authContext
    firestoreDB -->|stores| firestoreSvc

    %% Click Events
    click bottomSheet "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/BottomSheetComponent"
    click buildingsUI "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/Buildings"
    click floorSelector "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/FloorSelector"
    click placesInput "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/GooglePlacesInput"
    click mapComponent "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/components/Map.tsx"
    click mapButtons "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/components/MapButtons.tsx"
    click navigationUI "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/Navigation"
    click nextClassCard "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/NextClassComponent"
    click pois "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/POIs"
    click pinchPan "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/PinchPanContainer"
    click sharedUI "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/components/ui"
    click themedText "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/components/ThemedText.tsx"
    click themedView "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/components/ThemedView.tsx"

    click authContext "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/contexts/AuthContext/AuthContext.tsx"
    click buildingContext "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/contexts/BuildingContext/BuildingContext.tsx"
    click navigationContext "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/contexts/NavigationContext/NavigationContext.tsx"
    click themeContext "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/contexts/ThemeProvider/ThemeContext.ts"
    click globalProvider "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/contexts/ContextProvider/GlobalContextProvider.tsx"

    click googleAuth "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/hooks/useGoogleAuth.ts"
    click googleCalendar "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/hooks/useGoogleCalendar.ts"
    click selectedCalendar "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/hooks/useSelectedCalendar.ts"
    click nextEvent "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/hooks/useGoogleNextEvent.ts"
    click mapLocation "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/hooks/useMapLocation.ts"
    click mapsRoute "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/hooks/useGoogleMapsRoute.ts"
    click classTimer "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/hooks/useNextClassTimer.ts"

    click firestoreSvc "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/services/firestoreService.ts"
    click gCalSvc "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/services/googleCalendarService.ts"
    click gMapsSvc "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/services/googleMapsRoutes.ts"

    click firebaseCfg "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/firebase/firebaseConfig.ts"
    click expoCfg "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/app.config.js"
    click expoCfg "https://github.com/390minicapstone/polaris/blob/main/Polaris-FE/metro.config.cjs"

    click constants "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/constants"
    click utils "https://github.com/390minicapstone/polaris/tree/main/Polaris-FE/utils"

    classDef ui fill:#D0E8FF,stroke:#007BFF
    classDef state fill:#DFFFD0,stroke:#00A600
    classDef service fill:#FFE8A0,stroke:#FF8C00
    classDef external fill:#E0E0E0,stroke:#888888
```
