# pkwmapp/pkwmtt-frontend-mobile architecture

> Architecture diagram of the GitHub repository pkwmapp/pkwmtt-frontend-mobile, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pkwmapp/pkwmtt-frontend-mobile
- Repository: https://github.com/pkwmapp/pkwmtt-frontend-mobile

## Overview

##### Project type and purpose
- This is a React Native mobile application (“PKWM App”) written in TypeScript.
- It’s a standalone front-end that runs on both Android and iOS, consumes a timetable backend API, and exposes features such as calendar integration, localization, and in-app settings.

##### Main components of the system
A. Mobile Platforms & Native Shell
- Android (MainActivity.kt, Gradle build scripts)
- iOS (AppDelegate.swift, Xcode project files)
B. React Native Runtime & Bundler
- JS engine (Hermes/JavaScriptCore)
- Metro Bundler (development only)
C. Entry Point & Navigation
- index.js → App.tsx → tabNavigator.tsx (React Navigation)
D. UI Layer
- src/app – feature screens (Auth, Main, Tabs)
- src/components – reusable UI & modals
- src/styles – global + UI-specific styles
E. State Management
- React Hooks + Zustand-style stores in src/store (authStore, settingsStore)
F. Business Logic / Services
- src/services/api.ts – HTTP client to PKWMTT-backend
- CalendarService – native calendar integration
- TimetableService, SettingsService, VersionService
G. Shared Infrastructure
- src/constants – app-wide constants
- src/translation – i18n/locales, react-native-localize integration
H. Tests & Mocks
- __tests__ & __mocks__ (Jest + React Native Testing Library)
I. DevOps / CI
- GitHub Actions workflows (CICD, testdeploy)
- Docker referenced (containerized CI; no Dockerfile here)

##### Relationships & data flows
1. User taps UI → React Native UI components render via App.tsx + tabNavigator
2. Navigation handler invokes screen logic (e.g. TimetableScreen)
3. Screen calls Hooks or Service layer
- Services may read/write local device resources via Native Modules
– AsyncStorage, device info, calendar API
- Services call `api.ts` to perform HTTP(s) requests to external PKWMTT-backend
4. Store updates (authStore or settingsStore) and triggers UI re-render
5. i18n module resolves translations and date/number formatting

##### Architectural patterns & design principles
- Feature-based folder structure (group screens, services, components by domain)
- Separation of concerns:
- UI vs. state vs. business logic vs. data access
- Native modules isolated under services/calendar & core `api.ts`
- Unidirectional data flow: components → services → stores → UI
- Dependency Injection via module imports; no global singletons outside stores

##### Final recommendations
- Layers: Device OS, RN runtime, JS app structure, external services.
- Be precise with folder/module names and data flows.
- Avoid over-splitting—group related screens/components under “UI Layer.”

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Mobile Platforms
  subgraph "Mobile Platforms"
    Android["Android Native Shell"]:::platform
    iOS["iOS Native Shell"]:::platform
  end
  click Android "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/android/app/src/main/java/com/pkwmtt/MainActivity.kt"
  click Android "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/android/app/src/main/java/com/pkwmtt/MainApplication.kt"
  click iOS "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/ios/PKWMTT/AppDelegate.swift"
  click iOS "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/ios/PKWMTT.xcodeproj"

  %% React Native Core
  subgraph "React Native Core"
    Bridge["RN Bridge"]:::core
    JSEngine["JS Engine (Hermes/JavaScriptCore)"]:::core
    Metro["Metro Bundler (dev-only)"]:::dev
  end

  Android --> Bridge
  iOS --> Bridge
  Bridge <--> JSEngine
  Metro --> JSEngine

  %% JS Application Layers
  subgraph "JS Application"
    subgraph "Entry & Navigation"
      Index["index.js"]:::core
      App["App.tsx"]:::core
      Navigation["tabNavigator.tsx"]:::core
    end
    subgraph "UI Layer"
      Auth["Auth Flow Screens"]:::ui
      FirstTime["FirstTimeSetupScreen"]:::ui
      Tabs["Tab Screens"]:::ui
    end
    subgraph "Components & Styles"
      Components["UI Components"]:::ui
      Modals["Modals"]:::ui
      GlobalStyles["globalStyles.ts"]:::ui
      UIStyles["uiStyles"]:::ui
    end
    subgraph "Business Logic & Services"
      API["api.ts"]:::service
      CalendarSvc["CalendarService"]:::service
      TTService["TimetableService"]:::service
      CheckLesson["checkActiveLesson.ts"]:::service
      SettingsSvc["SettingsService"]:::service
      VersionSvc["versionService.ts"]:::service
    end
    subgraph "State Management Stores"
      AuthStore["authStore.ts"]:::store
      SettingsStore["settingsStore.ts"]:::store
    end
    subgraph "Shared Infrastructure"
      Utils["Utilities"]:::util
      Constants["Constants"]:::util
      I18n["i18n / Localization"]:::util
    end
  end

  %% External & Native Modules & CI
  subgraph "Native Modules"
    AsyncStorage["AsyncStorage"]:::native
    DeviceInfo["DeviceInfo"]:::native
    CalendarAPI["Calendar API"]:::native
  end
  subgraph "External Services"
    Backend["PKWMTT Backend API"]:::external
    AppStores["App Stores"]:::external
  end
  subgraph "CI/CD"
    CICD[".github/workflows/CICD.yml"]:::ci
    TestDeploy[".github/workflows/testdeploy.yml"]:::ci
  end

  %% Click Events
  click Index "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/index.js"
  click App "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/App.tsx"
  click Navigation "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/app/tabs/tabNavigator.tsx"
  click Auth "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/app/auth"
  click FirstTime "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/app/main/FirstTimeSetupScreen.tsx"
  click Tabs "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/app/tabs/CalculatorScreen"
  click Tabs "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/app/tabs/CalendarScreen"
  click Tabs "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/app/tabs/SettingsScreen"
  click Tabs "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/app/tabs/TimetableScreen"
  click Components "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/components"
  click Components "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/components/ui"
  click Modals "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/components/modals"
  click GlobalStyles "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/styles/globalStyles.ts"
  click UIStyles "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/styles/uiStyles"
  click API "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/services/api.ts"
  click CalendarSvc "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/services/calendar/CalendarService.ts"
  click TTService "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/services/timetable/TimetableService.ts"
  click CheckLesson "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/services/timetable/checkActiveLesson.ts"
  click SettingsSvc "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/services/settings/SettingsService.ts"
  click VersionSvc "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/services/versionService.ts"
  click AuthStore "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/store/authStore.ts"
  click SettingsStore "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/store/settingsStore.ts"
  click Utils "https://github.com/pkwmapp/pkwmtt-frontend-mobile/tree/main/src/utils"
  click Constants "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/constants/constants.ts"
  click I18n "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/translation/locales/en.json"
  click I18n "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/src/translation/locales/pl.json"
  click I18n "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/i18n.ts"
  click CICD "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/.github/workflows/CICD.yml"
  click TestDeploy "https://github.com/pkwmapp/pkwmtt-frontend-mobile/blob/main/.github/workflows/testdeploy.yml"

  %% Data Flows
  JSEngine --> Index
  Index --> App
  App --> Navigation
  Navigation --> Auth
  Navigation --> FirstTime
  Navigation --> Tabs
  Auth --> API
  FirstTime --> CalendarSvc
  Tabs --> API
  Tabs --> TTService
  API --> Backend
  CalendarSvc --> CalendarAPI
  TTService --> Backend
  CheckLesson --> AsyncStorage
  SettingsSvc --> SettingsStore
  VersionSvc --> Utils
  API --> SettingsSvc
  ServicesStores(("Business Logic & Services")) --> AuthStore
  ServicesStores --> SettingsStore
  AuthStore --> Auth
  SettingsStore --> UIStyles
  Utils --> Auth
  Constants --> UIStyles
  I18n --> Auth
  Bridge <--> AsyncStorage
  Bridge <--> DeviceInfo
  Bridge <--> CalendarAPI
  CICD --> AppStores

  %% Styles
  classDef platform fill:#b8e986,stroke:#5a8f00,color:#000
  classDef core fill:#a0c4ff,stroke:#3a6daf,color:#000
  classDef dev fill:#cdb4db,stroke:#885988,color:#000
  classDef ui fill:#d0f4de,stroke:#4b8f29,color:#000
  classDef service fill:#ffcc80,stroke:#c87f0a,color:#000
  classDef store fill:#fff59d,stroke:#b28f00,color:#000
  classDef util fill:#e0e0e0,stroke:#7a7a7a,color:#000
  classDef native fill:#e1bee7,stroke:#7a3b7a,color:#000
  classDef external fill:#ff8a80,stroke:#c03638,color:#000
  classDef ci fill:#b3e5fc,stroke:#0277bd,color:#000
```
