# saulamsal/apple-news-ui architecture

> Architecture diagram of the GitHub repository saulamsal/apple-news-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saulamsal/apple-news-ui
- Repository: https://github.com/saulamsal/apple-news-ui

## Overview

##### Main Components
- UI/Presentation Layer:
- The "app" directory contains the main screens and layouts using file-based routing (Expo Router). This includes separate subdirectories for tabs such as “index,news+,sports,audio,search”, “news+”, “search”, and “sports”. Note the dedicated pages for audio playback and content viewing.
- The "components" folder holds smaller reusable UI components (e.g., AnimatedAccordion, TabMenu, NewsItem, BottomSheet variants) that are used across the app’s user interface.
- Native Integrations & Modules:
- The "modules" directory shows integration with expo-live-activity that supports iOS Live Activities (using ActivityKit).
- The "targets" directory contains subprojects for native targets like watch and widget apps, evidencing support for watch apps, home screen widgets, and other iOS-specific features.
- Data Layer:
- Several JSON datasets exist in both "app/data" and "data" directories (e.g., entities.json, podcasts.json, podcasts scores) to serve as local data for news, podcasts, and more.
- External API integrations are hinted in the README (e.g., Apple Podcasts API).
- Navigation & Routing:
- Expo Router and React Navigation are core parts of the routing strategy. File-based navigation in the "app" directory uses layouts and tabs to separate and manage different app sections.
- State Management & Contexts:
- The "contexts" directory provides global state (e.g., AudioContext, RootScaleContext) to share app-wide data like audio playback state.
- The "hooks" directory further supports reactive UI behavior (e.g., useColorScheme, useThemeColor).

##### Relationships and Interactions
- The UI Layer (screens in the "app" directory) uses navigation (Expo Router / React Navigation) to switch between tabs (news, sports, audio, etc.).
- Components leverage shared contexts and hooks to get state updates (like the audio player state, overlay views, gesture interactions) and render accordingly.
- User interactions (swipe, tap, long press) are handled with React Native Gesture Handler and Reanimated, connecting with animated UI components.
- The Audio Module (located both in “app/audio” and components such as AudioVisualizer, MiniPlayer, and ExpandedPlayer) interacts with Expo AV (and the upcoming expo-audio) for playback, while integrating with native lock screen controls and background audio functionalities.
- Native features (Live Activities and Widgets) in “modules” and “targets” directly interface with iOS frameworks such as WidgetKit and ActivityKit.
- Data fetching or local data reads (JSON files within “data” and “app/data”) feed the UI, while helper functions and utilities (e.g., in the "helper" and "utils" directories) format and process this data.

##### Architectural Patterns & Design Principles
- File-based Routing: The structure in the “app” directory implies a declarative, file-based routing strategy which aligns with Expo Router practices.
- Component-Based UI: Reusable components and clearly separated UI logic promote maintainability and scalability.
- Separation of Concerns: There is a clear separation between UI components, business logic (contexts, hooks), and native integrations.
- Cross-Platform Modularization: The code supports distinct native modules for iOS (widgets, watch apps) while sharing common business logic across iOS, Android, and Web.

##### Technologies & Frameworks
- Core Technologies: React Native, Expo, TypeScript, and Tailwind CSS
- Navigation: Expo Router and React Navigation
- Animation & Gestures: Reanimated and Gesture Handler
- Audio: Expo AV (and an upcoming switch to expo-audio)
- Native iOS Features: WidgetKit, ActivityKit, and native watch support
- Storage/State: MMKV and custom context/hooks implementations

##### Specific Elements
- Component Labels: Clearly label nodes for "App Screens (file-based routing)", "Reusable Components", "Navigation & Routing", "State Management & Contexts", "Data Sources", "Audio Playback Module", and "Native Integrations (Widgets, Live Activities, Watch)".
- Interconnections: Illustrate the data flow from user actions on UI components, through gesture and animation handlers, to the audio module and external native features.

- Shared contexts and hooks that enable state management which is consumed by UI components.
- Out the navigation system (Expo Router and React Navigation) that links the screens.
- Native integration modules and targets (expo-live-activity, widget, watch support).

## Diagram (Mermaid)

```mermaid
flowchart TD
    R("Apple News Clone"):::core

    subgraph "UI Layer"
        UI("App Screens (File-based Routing)"):::ui
        AUDIO("Audio Playback Module"):::audio
    end

    subgraph "Reusable Components"
        COMP_UI("Reusable UI Components"):::comps
        NAV("Navigation & Routing"):::nav
    end

    subgraph "Business Logic"
        STATE("State Management & Contexts"):::state
        HOOKS("Reactive Hooks for UI Behavior"):::hooks
    end

    subgraph "Data Layer"
        DATA("Data Layer (Local JSON & APIs)"):::data
    end

    subgraph "Native Modules"
        NATIVE("Native Integrations (Widgets,LiveActivities,Watch)"):::native
    end

    R --> UI
    R --> COMP_UI
    R --> STATE
    R --> HOOKS
    R --> DATA
    R --> NATIVE

    UI -->|"routes"| NAV
    UI -->|"consumesState"| STATE
    UI -->|"usesHooks"| HOOKS
    COMP_UI -->|"embeddedIn"| UI
    STATE -->|"sharedWith"| COMP_UI
    DATA -->|"feedsUI"| UI
    DATA -->|"feedsAudio"| AUDIO
    AUDIO -->|"integratesWith"| NATIVE
    NATIVE -->|"enhancesUI"| UI
    AUDIO -->|"rendersIn"| UI
    HOOKS -->|"dynamicBehavior"| COMP_UI

    click UI "https://github.com/saulamsal/apple-news-ui/blob/main/app/(tabs)/_layout.tsx"
    click COMP_UI "https://github.com/saulamsal/apple-news-ui/tree/main/components/"
    click NAV "https://github.com/saulamsal/apple-news-ui/blob/main/components/navigation/NativeTabs.tsx"
    click STATE "https://github.com/saulamsal/apple-news-ui/blob/main/contexts/AudioContext.tsx"
    click HOOKS "https://github.com/saulamsal/apple-news-ui/blob/main/hooks/useColorScheme.ts"
    click DATA "https://github.com/saulamsal/apple-news-ui/blob/main/data/news.json"
    click AUDIO "https://github.com/saulamsal/apple-news-ui/blob/main/app/audio/[id].tsx"
    click NATIVE "https://github.com/saulamsal/apple-news-ui/tree/main/modules/expo-live-activity/"

    classDef core fill:#ffffff,stroke:#000,stroke-width:2px;
    classDef ui fill:#f9c74f,stroke:#333,stroke-width:2px;
    classDef comps fill:#90be6d,stroke:#333,stroke-width:2px;
    classDef nav fill:#577590,stroke:#fff,stroke-width:2px;
    classDef state fill:#43aa8b,stroke:#333,stroke-width:2px;
    classDef hooks fill:#f3722c,stroke:#333,stroke-width:2px;
    classDef data fill:#f94144,stroke:#333,stroke-width:2px;
    classDef audio fill:#277da1,stroke:#333,stroke-width:2px;
    classDef native fill:#6a4c93,stroke:#fff,stroke-width:2px;
```
