# fahcode/xiaoshuo-native architecture

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

- Interactive diagram: https://gitdiagram.com/fahcode/xiaoshuo-native
- Repository: https://github.com/fahcode/xiaoshuo-native

## Overview

##### Project type and purpose
- This is a React Native mobile application (“xiaoshuo-native”), a novel/e-book reader for iOS and Android.
- It bundles JavaScript UI code, a Redux-based state layer, a native bridge (React Native runtime), and uses network calls plus local persistence (Realm) to fetch and cache book data.

##### File structure
- Top-level “android” and “ios” folders contain the native projects and entry-point code (MainActivity.java, AppDelegate.m).
- “src” holds all React Native JavaScript:
- components/ (stateless, presentational UI)
- containers/ (stateful, connect to Redux store)
- routers/ (navigation definitions)
- store/ (Redux actions, reducers, store configuration)
- util/ (network fetch, Realm wrapper, WebSocket helper, common styles)
- “App.js” and “index.js” bootstrap the JS app via Metro bundler.
- README describes build steps (react-native start, run-android, assembleRelease).

##### README for additional insights
- No backend code is included; the mobile app relies on remote HTTP APIs (via util/fetch.js) and/or WebSockets (util/Socket.js).
- It uses Realm for on-device data caching (util/realm.js).

##### Components
a. Main components
- Mobile UI Layer (React components + React Navigation)
- State Management Layer (Redux Store + Actions + Reducers)
- Data Layer
- Network Module (fetch.js)
- WebSocket Client (Socket.js)
- Local Persistence (Realm DB)
- Native Host (React Native Bridge on iOS & Android)
- External Services
- Book Data REST APIs
- Real-time update WebSocket server (if in use)
b. Relationships & interactions
1. User taps UI → container dispatches Redux action
2. Action middleware calls fetch.js or Socket.js → HTTP/WebSocket → external API
3. Response → action payload → reducer updates Redux store
4. Store update → container re-renders component → UI reflects new data
5. Selected data also written to Realm for offline caching → read from Realm when offline
6. Metro Bundler serves JS bundle at runtime; native host packages JS for release
c. Architectural patterns & design principles
- Flux/Redux unidirectional data flow: UI → Action → Reducer → Store → UI
- Separation of concerns:
- Presentational vs. Container components
- Network layer abstracted in util/fetch.js
- Persistence abstracted in util/realm.js
- Offline-first caching pattern: fallback to Realm if network unavailable
d. Key technologies
- React Native (JS runtime + native bridge)
- Redux (state container)
- Realm (local mobile database)
- JavaScript Fetch API & WebSockets
- Metro bundler (module resolution & hot reload)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    user("User"):::user

    %% Native Host and Bundler
    subgraph "Native Host (Android & iOS)" 
        direction TB
        metro["Metro Bundler\n(metro.config.js)"]:::infra
        indexJS["Entry Point\nindex.js"]:::entry
        appJS["App Bootstrap\nApp.js"]:::entry
    end

    %% JavaScript Application Layer
    subgraph "JS Application"
        direction TB

        router["React Navigation\nsrc/routers/index.js"]:::router

        subgraph "UI Layer"
            direction TB
            present["Presentational Components\nsrc/components/"]:::ui
            container["Container Components\nsrc/containers/"]:::container
        end

        subgraph "State Management (Redux)"
            direction TB
            store["Configure Store\nsrc/store/configureStore.js"]:::state
            actions["Redux Actions\nsrc/store/actions/"]:::state
            reducers["Redux Reducers\nsrc/store/reducers/"]:::state
        end

        subgraph "Data Layer"
            direction TB
            fetch["Network Module\nsrc/util/fetch.js"]:::util
            socket["WebSocket Client\nsrc/util/Socket.js"]:::util
            realmUtil["Realm Wrapper\nsrc/util/realm.js"]:::util
            realmDB["Realm Database"]:::db
        end
    end

    %% External Services
    subgraph "External Services"
        direction TB
        api["Book Data REST API"]:::external
        ws["WebSocket Server"]:::external
    end

    %% Flows
    user -->|"taps UI"| present
    present -->|"calls"| container
    container -->|"dispatch"| actions
    actions -->|"invoke"| fetch
    fetch -->|"HTTP request"| api
    api -->|"HTTP response"| fetch
    fetch -->|"response payload"| actions
    actions -->|"invoke"| socket
    socket -->|"WS connect"| ws
    ws -->|"WS message"| socket
    socket -->|"message payload"| actions
    actions -->|"write cache"| realmUtil
    realmUtil -->|"realm.write"| realmDB
    realmDB -->|"realm.read"| realmUtil
    realmUtil -->|"cache data"| actions
    actions -->|"payload"| reducers
    reducers -->|"new state"| store
    store -->|"state update"| container
    container -->|"re-render"| present

    indexJS -->|"bootstrap"| router
    appJS -->|"render App"| router
    metro -->|"serves bundle"| indexJS

    %% Click Events
    click present "https://github.com/fahcode/xiaoshuo-native/tree/master/src/components/"
    click container "https://github.com/fahcode/xiaoshuo-native/tree/master/src/containers/"
    click router "https://github.com/fahcode/xiaoshuo-native/blob/master/src/routers/index.js"
    click store "https://github.com/fahcode/xiaoshuo-native/blob/master/src/store/configureStore.js"
    click actions "https://github.com/fahcode/xiaoshuo-native/tree/master/src/store/actions/"
    click reducers "https://github.com/fahcode/xiaoshuo-native/tree/master/src/store/reducers/"
    click fetch "https://github.com/fahcode/xiaoshuo-native/blob/master/src/util/fetch.js"
    click socket "https://github.com/fahcode/xiaoshuo-native/blob/master/src/util/Socket.js"
    click realmUtil "https://github.com/fahcode/xiaoshuo-native/blob/master/src/util/realm.js"
    click indexJS "https://github.com/fahcode/xiaoshuo-native/blob/master/index.js"
    click appJS "https://github.com/fahcode/xiaoshuo-native/blob/master/App.js"
    click metro "https://github.com/fahcode/xiaoshuo-native/blob/master/metro.config.js"

    %% Styles
    classDef user fill:#fff,stroke:#333,stroke-width:1px
    classDef infra fill:#ddd,stroke:#333,stroke-width:1px
    classDef entry fill:#aff,stroke:#333,stroke-width:1px
    classDef router fill:#cff,stroke:#333,stroke-width:1px
    classDef ui fill:#ccf,stroke:#333,stroke-width:1px
    classDef container fill:#ccf,stroke:#333,stroke-width:1px
    classDef state fill:#cfc,stroke:#333,stroke-width:1px
    classDef util fill:#fcf,stroke:#333,stroke-width:1px
    classDef db fill:#fca,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px
```
