# saiyedrushan/hadithstash architecture

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

- Interactive diagram: https://gitdiagram.com/saiyedrushan/hadithstash
- Repository: https://github.com/saiyedrushan/hadithstash

## Overview

##### Project type and purpose
- This is a cross-platform mobile application built with Expo (React Native) using Expo Router’s file-based routing.
- From the file tree and README, it appears to be a reading app (Hadith/book/chapter navigation) with three main tabs (Home, Library, Profile) and deep routes for books, chapters, and hadiths.
- It uses Supabase for backend services (authentication, database) and AsyncStorage for local persistence.

##### File structure
- Top-level directories:
- app/ – Exposes the file-based routing structure under (tabs) and flat routes
- components/ – Reusable UI components (cards, themed views, collapsibles, etc.)
- assets/ – Fonts and images
- libs/ – Abstraction over Supabase client (supabase.ts)
- constants/, types/ – Shared constants and TypeScript types
- scripts/ – Utility scripts (e.g., reset project)
- Configuration files: app.json (Expo config), tsconfig.json, package.json
- Testing assets under components/__tests__

##### README for additional insights
- Confirms this was bootstrapped with create-expo-app.
- No built-in backend in this repo beyond the Supabase client abstraction.
- Emphasizes file-based routing and standard Expo development flows.

a. Main components to represent:
1. Mobile Client (iOS, Android, Web)
- Presentation Layer (Screens under app/(tabs) + index.tsx)
- Navigation Layer (Expo Router, file-based routing)
- UI Components (components/* & components/ui/*)
- Hooks & State (hooks/*, constants/*, useThemeColor, AsyncStorage)
- Data Layer (libs/supabase.ts + types/supabase.ts)
2. Local Persistence
- AsyncStorage (types/asyncstorage.ts) for caching last-read state, theme prefs
3. External Service
- Supabase (Auth, Realtime DB, Storage)
4. Assets
- Fonts & Images (assets/fonts, assets/images)
5. Build & Deployment
- Expo CLI/Metro bundler (app.json, package.json scripts)

b. Relationships and interactions
- Screens call UI Components and Hooks.
- Hooks/data layer call libs/supabase to fetch or write data.
- libs/supabase communicates over HTTPS with Supabase Auth/DB.
- Successful API responses flow back into data layer → hooks → components → UI.
- Some state is persisted locally in AsyncStorage.
- Navigation orchestrates which screen is active based on route segments.
- Assets are loaded by UI components at render time.

c. Architectural patterns & design principles
- Component-based UI (React) separating presentational vs data concerns.
- File-based routing for screen discovery (Expo Router).
- Unidirectional data flow: UI → Hooks/Data Layer → External Service → UI.
- Abstraction of backend via libs/supabase to centralize API calls.
- Separation of concerns: “app/” for routes, “components/” for UI, “hooks/” for logic, “libs/” for external integrations.

d. Key technologies & libraries
- Expo (React Native)
- Expo Router (file-based navigation)
- React & React Native components
- Supabase JS client
- TypeScript
- AsyncStorage
- Jest (components/__tests__)
- Metro bundler & Expo CLI

##### Diagramming conventions
- Use clear, concise labels: e.g., “HomeScreen”, “Supabase Service”, “AsyncStorage”
- From Screens → Hooks/Data Layer → Supabase
- From Supabase → Data Layer → Screens
- From Screens ↔ AsyncStorage
- Orange for External Service (Supabase)

##### Detailed coverage
- Within Data Layer, break out functions like “fetchHadith()”, “loginUser()” if desired.
- If the script “reset-project.js” is important for CI/CD or developer workflows, show it as part of Build & Deployment.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Platform Targets
    PlatformTargets["Platform Targets: iOS, Android, Web"]:::note

    %% Mobile Client Box
    subgraph "Mobile Client (Expo)" 
        direction TB

        %% Routing & Screens
        subgraph "Routing & Screens" 
            direction TB
            LayoutRoot["_layout.tsx"]:::ui
            Index["index.tsx"]:::ui
            NotFound["+not-found.tsx"]:::ui

            subgraph "Tabs" 
                direction TB
                TabLayout["_layout.tsx"]:::ui
                HomeIndex["home/index.tsx"]:::ui
                HomeBook["home/book/[id].tsx"]:::ui
                HomeChapter["home/book/[bookId]/chapter/[id].tsx"]:::ui
                HomeHadith["home/book/[bookId]/chapter/[chapterId]/hadith/[id].tsx"]:::ui
                LibraryTab["library.tsx"]:::ui
                ProfileTab["profile.tsx"]:::ui
            end
        end

        %% UI Components
        subgraph "UI Components" 
            direction TB
            BookCard["BookCard.tsx"]:::ui
            HadithCard["HadithCard.tsx"]:::ui
            LastReadBar["LastReadBar.tsx"]:::ui
            Collapsible["Collapsible.tsx"]:::ui
            ContainerView["ContainerView.tsx"]:::ui
            ThemedText["ThemedText.tsx"]:::ui
            ThemedView["ThemedView.tsx"]:::ui
            AuthComp["Auth.tsx"]:::ui
            ExternalLink["ExternalLink.tsx"]:::ui
            HapticTab["HapticTab.tsx"]:::ui
            IconSymbol["ui/IconSymbol.tsx"]:::ui
            TabBarBackground["ui/TabBarBackground.tsx"]:::ui
        end

        %% Hooks & State
        subgraph "Hooks & State Management" 
            direction TB
            UseColorScheme["useColorScheme.ts"]:::logic
            UseColorSchemeWeb["useColorScheme.web.ts"]:::logic
            UseThemeColor["useThemeColor.ts"]:::logic
            ColorsConst["Colors.ts"]:::logic
        end

        %% Data Layer
        subgraph "Data Layer" 
            direction TB
            SupabaseLib["supabase.ts"]:::logic
            SupabaseTypes["supsabase.ts"]:::logic
        end

        %% Local Persistence
        AsyncStorage["AsyncStorage (types/asyncstorage.ts)"]:::storage
    end

    %% External Service
    Supabase["Supabase Service (Auth, DB, Storage)"]:::external

    %% Assets
    Assets["Assets (fonts/, images/)"]:::assets

    %% Build & Deployment
    subgraph "Build & Deployment"
        direction TB
        AppJSON["app.json"]:::build
        PackageJSON["package.json"]:::build
        PackageLock["package-lock.json"]:::build
        TSConfig["tsconfig.json"]:::build
        ResetScript["reset-project.js"]:::build
    end

    %% Connections
    LayoutRoot -->|uses| Index
    Index -->|routes| TabLayout
    TabLayout -->|renders| HomeIndex
    HomeIndex -->|navigates| HomeBook
    HomeBook -->|navigates| HomeChapter
    HomeChapter -->|navigates| HomeHadith
    TabLayout -->|renders| LibraryTab
    TabLayout -->|renders| ProfileTab

    HomeIndex -->|renders| BookCard
    HomeHadith -->|renders| HadithCard
    HomeIndex -->|uses| LastReadBar
    HomeIndex -->|uses| Collapsible

    Index -->|wraps| ContainerView
    AllUIComponents -->|use| ThemedText
    AllUIComponents -->|use| ThemedView
    AllUIComponents -->|use| IconSymbol
    AllUIComponents -->|use| TabBarBackground

    %% Hooks interactions
    LayoutRoot -->|uses| UseThemeColor
    AllScreens -->|use| UseColorScheme
    AllScreens -->|use| UseColorSchemeWeb
    AllScreens -->|use| ColorsConst

    %% Data Flow
    AllHooks -->|call| SupabaseLib
    SupabaseLib -->|defines types| SupabaseTypes
    SupabaseLib -->|HTTP| Supabase
    Supabase -->|response| SupabaseLib
    SupabaseLib -->|provides data| AllHooks
    AllHooks -->|provides props| AllUIComponents

    %% AsyncStorage
    AllScreens -->|read/write| AsyncStorage
    AsyncStorage -->|caches| AllHooks

    %% Assets
    AllUIComponents -->|load| Assets

    %% Build & Deployment
    AppJSON -->|configures| LayoutRoot
    PackageJSON -->|scripts| ResetScript
    TSConfig -->|types| AllSources

    %% Click Events
    click LayoutRoot "https://github.com/saiyedrushan/hadithstash/blob/main/app/_layout.tsx"
    click Index "https://github.com/saiyedrushan/hadithstash/blob/main/app/index.tsx"
    click NotFound "https://github.com/saiyedrushan/hadithstash/blob/main/app/+not-found.tsx"
    click TabLayout "https://github.com/saiyedrushan/hadithstash/blob/main/app/(tabs)/_layout.tsx"
    click HomeIndex "https://github.com/saiyedrushan/hadithstash/blob/main/app/(tabs)/home/index.tsx"
    click HomeBook "https://github.com/saiyedrushan/hadithstash/blob/main/app/(tabs)/home/book/[id].tsx"
    click HomeChapter "https://github.com/saiyedrushan/hadithstash/blob/main/app/(tabs)/home/book/[bookId]/chapter/[id].tsx"
    click HomeHadith "https://github.com/saiyedrushan/hadithstash/blob/main/app/(tabs)/home/book/[bookId]/chapter/[chapterId]/hadith/[id].tsx"
    click LibraryTab "https://github.com/saiyedrushan/hadithstash/blob/main/app/(tabs)/library.tsx"
    click ProfileTab "https://github.com/saiyedrushan/hadithstash/blob/main/app/(tabs)/profile.tsx"
    click BookCard "https://github.com/saiyedrushan/hadithstash/blob/main/components/BookCard.tsx"
    click HadithCard "https://github.com/saiyedrushan/hadithstash/blob/main/components/HadithCard.tsx"
    click LastReadBar "https://github.com/saiyedrushan/hadithstash/blob/main/components/LastReadBar.tsx"
    click Collapsible "https://github.com/saiyedrushan/hadithstash/blob/main/components/Collapsible.tsx"
    click ContainerView "https://github.com/saiyedrushan/hadithstash/blob/main/components/ContainerView.tsx"
    click ThemedText "https://github.com/saiyedrushan/hadithstash/blob/main/components/ThemedText.tsx"
    click ThemedView "https://github.com/saiyedrushan/hadithstash/blob/main/components/ThemedView.tsx"
    click AuthComp "https://github.com/saiyedrushan/hadithstash/blob/main/components/Auth.tsx"
    click ExternalLink "https://github.com/saiyedrushan/hadithstash/blob/main/components/ExternalLink.tsx"
    click HapticTab "https://github.com/saiyedrushan/hadithstash/blob/main/components/HapticTab.tsx"
    click IconSymbol "https://github.com/saiyedrushan/hadithstash/blob/main/components/ui/IconSymbol.tsx"
    click TabBarBackground "https://github.com/saiyedrushan/hadithstash/blob/main/components/ui/TabBarBackground.tsx"
    click UseColorScheme "https://github.com/saiyedrushan/hadithstash/blob/main/hooks/useColorScheme.ts"
    click UseColorSchemeWeb "https://github.com/saiyedrushan/hadithstash/blob/main/hooks/useColorScheme.web.ts"
    click UseThemeColor "https://github.com/saiyedrushan/hadithstash/blob/main/hooks/useThemeColor.ts"
    click ColorsConst "https://github.com/saiyedrushan/hadithstash/blob/main/constants/Colors.ts"
    click SupabaseLib "https://github.com/saiyedrushan/hadithstash/blob/main/libs/supabase.ts"
    click SupabaseTypes "https://github.com/saiyedrushan/hadithstash/blob/main/types/supabase.ts"
    click AsyncStorage "https://github.com/saiyedrushan/hadithstash/blob/main/types/asyncstorage.ts"
    click Assets "https://github.com/saiyedrushan/hadithstash/tree/main/assets/"
    click AppJSON "https://github.com/saiyedrushan/hadithstash/blob/main/app.json"
    click PackageJSON "https://github.com/saiyedrushan/hadithstash/blob/main/package.json"
    click PackageLock "https://github.com/saiyedrushan/hadithstash/blob/main/package-lock.json"
    click TSConfig "https://github.com/saiyedrushan/hadithstash/blob/main/tsconfig.json"
    click ResetScript "https://github.com/saiyedrushan/hadithstash/blob/main/scripts/reset-project.js"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6
    classDef logic fill:#DFFFE0,stroke:#228B22
    classDef external fill:#FFE0B2,stroke:#FF8C00
    classDef storage fill:#E0E0E0,stroke:#888
    classDef assets fill:#FFF4C1,stroke:#DAA520
    classDef build fill:#F0E6FF,stroke:#800080
    classDef note fill:#F5F5F5,stroke:#666
    class AllUIComponents,AllScreens,AllHooks,AllSources internal
    class AllUIComponents,AllScreens,AllHooks,AllSources ui
    class AllUIComponents,AllScreens,AllHooks,AllSources logic
```
