# akamfoad/hacker-native architecture

> Architecture diagram of the GitHub repository akamfoad/hacker-native, 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/akamfoad/hacker-native
- Repository: https://github.com/akamfoad/hacker-native

## Overview

##### Project type and purpose
- This is a React Native mobile client (Expo-based) for browsing Hacker News content.
- It uses Expo’s managed workflow, React/TypeScript, the new app‑directory-based router, and fetches data from the public Hacker News API.

##### File structure
- Top‑level config: `.eslintrc.js`, `tsconfig.json`, `babel.config.js`, `app.json`, `package.json`.
- `app/`: Expo Router screens and layouts (`index.tsx`, `[itemId].tsx`, `users/[userId].tsx`, `_layout.tsx`).
- `api/`: Data‑fetching layer (`endpoints.ts`).
- `components/`: Reusable UI components organized by domain (`posts/`, `comments/`, common controls like `Spinner.tsx`, `Select.tsx`).
- `shared/`: Cross‑cutting TypeScript types.
- `lib/`: Utility functions (text processing).
- `scripts/`: Automation scripts (e.g., `reset-project.js`).

##### Key insights from the README
- Expo project built with `create-expo-app`.
- Supports listing and filtering HN stories, viewing post details, comments, and user profiles.
- No custom backend—relies on Hacker News’s public REST endpoints (`topstories.json`, etc.).

##### Main components
a. Mobile Client (Expo App)
- Screens & Navigation (Expo Router)
- UI Components (PostsList, PostDetails, CommentDetails, UserProfile)
- State & Caching (in‑memory React state + optionally React Query or Context)
b. Data Layer (api/endpoints.ts)
- HTTP client to Hacker News REST API
c. Utilities & Shared Types
- Text processing, constants, TS types
d. Assets
e. External Service
- Hacker News public API (Firebase‑backed JSON endpoints)

##### Relationships and interactions
- Navigation routes map to Screens in `app/`.
- Screens render UI Components (`components/`) and invoke functions in `api/endpoints.ts`.
- API calls fetch JSON from the Hacker News API and return typed objects (`shared/types.ts`).
- Screens pass data to presentational components.
- Utilities in `lib/` transform raw API data for rendering.

##### Architectural patterns and design principles
- Separation of Concerns:
- Presentation (components/) vs Data‑fetching (api/) vs Routing (app/) vs Utilities (lib/, constants/).
- Modular, feature‑based directory structure (posts, comments, users).
- Typed contracts across layers via shared/types.ts.
- Asset bundling by Expo.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Mobile App Container
    subgraph "Mobile App (Expo/React Native)"
        direction TB

        %% Navigation Layer
        Navigation["Navigation (Expo Router)"]:::frontend
        click Navigation "https://github.com/akamfoad/hacker-native/blob/main/app/_layout.tsx"

        %% Screens Layer
        subgraph "Screens" 
            direction TB
            HomeScreen["Home Screen"]:::frontend
            click HomeScreen "https://github.com/akamfoad/hacker-native/blob/main/app/index.tsx"
            PostDetailsScreen["Post Details Screen"]:::frontend
            click PostDetailsScreen "https://github.com/akamfoad/hacker-native/blob/main/app/[itemId].tsx"
            UserProfileScreen["User Profile Screen"]:::frontend
            click UserProfileScreen "https://github.com/akamfoad/hacker-native/blob/main/app/users/[userId].tsx"
        end

        %% UI Components
        subgraph "UI Components"
            direction TB
            PostsList["PostsList Component"]:::frontend
            click PostsList "https://github.com/akamfoad/hacker-native/blob/main/components/posts/Posts.tsx"
            PostItem["Post Component"]:::frontend
            click PostItem "https://github.com/akamfoad/hacker-native/blob/main/components/posts/Post.tsx"
            UserActivities["User Activities Component"]:::frontend
            click UserActivities "https://github.com/akamfoad/hacker-native/blob/main/components/posts/user-activities/UserActivities.tsx"
            CommentsList["Comments List Component"]:::frontend
            click CommentsList "https://github.com/akamfoad/hacker-native/blob/main/components/comments/comments.tsx"
            CommentItem["Comment Component"]:::frontend
            click CommentItem "https://github.com/akamfoad/hacker-native/blob/main/components/comments/comment.tsx"
            Avatar["Avatar Control Component"]:::frontend
            click Avatar "https://github.com/akamfoad/hacker-native/blob/main/components/Avatar.tsx"
            Select["Select Control Component"]:::frontend
            click Select "https://github.com/akamfoad/hacker-native/blob/main/components/Select.tsx"
            Spinner["Spinner Control Component"]:::frontend
            click Spinner "https://github.com/akamfoad/hacker-native/blob/main/components/Spinner.tsx"
        end

        %% Data Layer
        API["Data‑fetching Layer"]:::datafetch
        click API "https://github.com/akamfoad/hacker-native/blob/main/api/endpoints.ts"

        %% Utilities & Constants
        subgraph "Utilities & Constants"
            direction TB
            TextUtils["Text Utilities"]:::utils
            click TextUtils "https://github.com/akamfoad/hacker-native/blob/main/lib/text.ts"
            SharedTypes["Shared Type Definitions"]:::utils
            click SharedTypes "https://github.com/akamfoad/hacker-native/blob/main/shared/types.ts"
            subgraph "Constants"
                Colors["Color Constants"]:::utils
                click Colors "https://github.com/akamfoad/hacker-native/blob/main/constants/Colors.ts"
                ItemTypes["Item Type Constants"]:::utils
                click ItemTypes "https://github.com/akamfoad/hacker-native/blob/main/constants/item.ts"
                Pagination["Pagination Constants"]:::utils
                click Pagination "https://github.com/akamfoad/hacker-native/blob/main/constants/pagination.ts"
                Stories["Stories Constants"]:::utils
                click Stories "https://github.com/akamfoad/hacker-native/blob/main/constants/stories.ts"
                UserConst["User Constants"]:::utils
                click UserConst "https://github.com/akamfoad/hacker-native/blob/main/constants/user.ts"
            end
        end

        %% Assets
        subgraph "Assets"
            direction TB
            Logo["Icon Asset (Logo)"]:::utils
            click Logo "https://github.com/akamfoad/hacker-native/blob/main/assets/icons/logo.tsx"
            Fonts["Font Assets"]:::utils
            click Fonts "https://github.com/akamfoad/hacker-native/tree/main/assets/fonts/"
            Images["Image Assets"]:::utils
            click Images "https://github.com/akamfoad/hacker-native/tree/main/assets/images/"
        end

        %% Scripts
        ResetScript["Project Reset Script"]:::utils
        click ResetScript "https://github.com/akamfoad/hacker-native/blob/main/scripts/reset-project.js"
    end

    %% External Service
    HNAPI["Hacker News API"]:::external

    %% Flow Relationships
    User["User"] -->|"taps"| Navigation
    Navigation -->|"navigates to"| HomeScreen
    Navigation -->|"navigates to"| PostDetailsScreen
    Navigation -->|"navigates to"| UserProfileScreen

    HomeScreen -->|"renders"| PostsList
    HomeScreen -->|"invokes"| API

    PostDetailsScreen -->|"renders"| PostItem
    PostDetailsScreen -->|"invokes"| API

    PostDetailsScreen -->|"renders"| CommentsList
    CommentsList -->|"renders"| CommentItem

    UserProfileScreen -->|"renders"| UserActivities

    API -->|"fetches JSON"| HNAPI
    HNAPI -->|"returns JSON"| API
    API -->|"returns typed data"| HomeScreen
    API -->|"returns typed data"| PostDetailsScreen
    API -->|"returns typed data"| UserProfileScreen

    HomeScreen -->|"uses"| SharedTypes
    PostDetailsScreen -->|"uses"| SharedTypes
    UserProfileScreen -->|"uses"| SharedTypes

    HomeScreen -->|"uses"| Colors
    HomeScreen -->|"uses"| Pagination
    HomeScreen -->|"uses"| Stories

    PostDetailsScreen -->|"uses"| ItemTypes
    UserProfileScreen -->|"uses"| UserConst

    HomeScreen -->|"transforms data"| TextUtils
    PostDetailsScreen -->|"transforms data"| TextUtils

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef datafetch fill:#98FB98,stroke:#333,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFD700,stroke:#333,stroke-width:1px
```
