# nadermnsr/articles_app architecture

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

- Interactive diagram: https://gitdiagram.com/nadermnsr/articles_app
- Repository: https://github.com/nadermnsr/articles_app

## Overview

##### Project type and purpose
- This is a Flutter mobile client application (“articles_app”) that fetches and displays the New York Times “most viewed” articles.
- It uses a three-layer architecture (presentation → business logic → data) on top of Flutter’s cross-platform framework, integrating with an external REST API.

##### File structure
- Top‐level folders:
– android, ios: platform‐specific runner code and build configuration
– lib: the core Dart code, subdivided into api, bloc, repository, views, and entrypoints
– test, test_driver: unit and integration tests
– .github/workflows: CI definitions for Dart analysis, build, and Flutter driver tests
- Key patterns:
– BLoC for state management under lib/bloc/article
– Repository + Retrofit/Dio HTTP client under lib/api and lib/repository
– Generated model and client code via retrofit and JsonSerializable
- Configuration:
– pubspec.yaml defines dependencies (flutter_bloc, dio, retrofit, json_serializable, flutter_driver)
– Gradle and Xcode project files for Android and iOS respectively

##### Extract insights from the README
- BLoC architecture (flutter_bloc) for predictable state management
- retrofit + dio for HTTP API consumption and code generation
- Tests: bloc_test for unit testing BLoC; flutter_driver for integration tests
- CI pipelines in .github/workflows for linting, test, coverage, and drive tests

##### Main components and their relationships
a. Presentation Layer (UI)
- Widgets under lib/views:
– ArticlesListView + ArticleCard: displays list of articles
– ArticleDetailsView + ArticleImage: renders details of a selected article
- App entrypoints: lib/main.dart → instantiates App (lib/app.dart) → wires up routing and drawer (lib/app_drawer.dart)

b. Business Logic Layer (BLoC)
- ArticleBloc, ArticleEvent, ArticleState in lib/bloc/article
- Receives UI events (e.g., FetchArticles), emits states (Loading, Loaded, Error)

c. Data Layer (Repository + API)
- ArticleRepository (lib/repository/repository.dart) orchestrates data access
- Data models under lib/repository/models (article.dart, media_item.dart, etc.) generated via json_serializable
- API client under lib/api/article_client.dart (Retrofit + Dio) calling NYT endpoints

d. External Service
- New York Times Most Viewed API (HTTPS REST)

e. Platform & Tooling
- Android (Gradle) and iOS (Xcode) launcher code
- CI pipelines (.github/workflows) for build, test, and integration drive

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Presentation Layer"
        direction TB
        ArticlesListView["ArticlesListView"]:::frontend
        ArticleCard["ArticleCard"]:::frontend
        ArticleDetailsView["ArticleDetailsView"]:::frontend
        ArticleImage["ArticleImage"]:::frontend
        Main["main.dart"]:::frontend
        App["app.dart"]:::frontend
        Drawer["app_drawer.dart"]:::frontend
    end

    subgraph "Business Logic Layer (BLoC)"
        direction TB
        Event["ArticleEvent"]:::bloc
        Bloc["ArticleBloc"]:::bloc
        State["ArticleState"]:::bloc
    end

    subgraph "Data Layer"
        direction TB
        ModelA["article.dart"]:::data
        ModelAG["article.g.dart"]:::data
        ModelM["media_item.dart"]:::data
        ModelMG["media_item.g.dart"]:::data
        ModelMM["media_metadata_item.dart"]:::data
        ModelMMG["media_metadata_item.g.dart"]:::data
        Repo["ArticleRepository"]:::data
        Client["ArticleClient"]:::data
        ClientG["ArticleClient.g.dart"]:::data
    end

    External["NYT API"]:::external

    subgraph "Platform Launchers"
        direction TB
        Android["MainActivity.kt"]:::platform
        iOS["AppDelegate.swift"]:::platform
    end

    subgraph "CI & Tests"
        direction TB
        CI1["dart.yml"]:::tests
        CI2["flutter-drive.yml"]:::tests
        UnitTest["article_bloc_test.dart"]:::tests
        Integration1["main.dart"]:::tests
        Integration2["main_test.dart"]:::tests
    end

    %% Interactions
    Main -->|instantiates| App
    App -->|uses| Drawer
    App -->|renders| ArticlesListView
    ArticleCard -->|navigates to| ArticleDetailsView

    ArticlesListView -.->|dispatch FetchArticles| Event
    Event -->|handled by| Bloc
    Bloc -->|emits states| State

    Bloc -->|"calls fetchArticles()"| Repo
    Repo -->|"GET /mostviewed"| Client
    Client -->|HTTPS request| External
    External -->|response| Client
    Client -->|data| Repo
    Repo -->|returns data| Bloc
    Bloc -->|state→Loaded| ArticlesListView
    Bloc -->|state→Loaded| ArticleDetailsView

    Android -->|launches| Main
    iOS -->|launches| Main

    UnitTest -->|tests| Bloc
    Integration1 -->|drives UI| Main
    Integration2 -->|drives UI| Main

    CI1 -->|runs| UnitTest
    CI1 -->|runs| Integration1
    CI2 -->|runs| Integration2

    %% Click Events
    click ArticlesListView "https://github.com/nadermnsr/articles_app/blob/main/lib/views/articles/articles.dart"
    click ArticleCard "https://github.com/nadermnsr/articles_app/blob/main/lib/views/articles/article_card.dart"
    click ArticleDetailsView "https://github.com/nadermnsr/articles_app/blob/main/lib/views/article_details/article_details.dart"
    click ArticleImage "https://github.com/nadermnsr/articles_app/blob/main/lib/views/article_details/article_image.dart"
    click Main "https://github.com/nadermnsr/articles_app/blob/main/lib/main.dart"
    click App "https://github.com/nadermnsr/articles_app/blob/main/lib/app.dart"
    click Drawer "https://github.com/nadermnsr/articles_app/blob/main/lib/app_drawer.dart"
    click Event "https://github.com/nadermnsr/articles_app/blob/main/lib/bloc/article/article_event.dart"
    click Bloc "https://github.com/nadermnsr/articles_app/blob/main/lib/bloc/article/article_bloc.dart"
    click State "https://github.com/nadermnsr/articles_app/blob/main/lib/bloc/article/article_state.dart"
    click Client "https://github.com/nadermnsr/articles_app/blob/main/lib/api/article_client.dart"
    click ClientG "https://github.com/nadermnsr/articles_app/blob/main/lib/api/article_client.g.dart"
    click Repo "https://github.com/nadermnsr/articles_app/blob/main/lib/repository/repository.dart"
    click ModelA "https://github.com/nadermnsr/articles_app/blob/main/lib/repository/models/article.dart"
    click ModelAG "https://github.com/nadermnsr/articles_app/blob/main/lib/repository/models/article.g.dart"
    click ModelM "https://github.com/nadermnsr/articles_app/blob/main/lib/repository/models/media_item.dart"
    click ModelMG "https://github.com/nadermnsr/articles_app/blob/main/lib/repository/models/media_item.g.dart"
    click ModelMM "https://github.com/nadermnsr/articles_app/blob/main/lib/repository/models/media_metadata_item.dart"
    click ModelMMG "https://github.com/nadermnsr/articles_app/blob/main/lib/repository/models/media_metadata_item.g.dart"
    click Android "https://github.com/nadermnsr/articles_app/blob/main/android/app/src/main/kotlin/com/example/articles_app/MainActivity.kt"
    click iOS "https://github.com/nadermnsr/articles_app/blob/main/ios/Runner/AppDelegate.swift"
    click CI1 "https://github.com/nadermnsr/articles_app/blob/main/.github/workflows/dart.yml"
    click CI2 "https://github.com/nadermnsr/articles_app/blob/main/.github/workflows/flutter-drive.yml"
    click UnitTest "https://github.com/nadermnsr/articles_app/blob/main/test/bloc_test/article_bloc_test.dart"
    click Integration1 "https://github.com/nadermnsr/articles_app/blob/main/test_driver/main.dart"
    click Integration2 "https://github.com/nadermnsr/articles_app/blob/main/test_driver/main_test.dart"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#333,stroke-width:1px
    classDef bloc fill:#D6FFD6,stroke:#333,stroke-width:1px
    classDef data fill:#FFE4B3,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef platform fill:#F0F0F0,stroke:#333,stroke-width:1px
    classDef tests fill:#F5E6FF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
