# josedev155/flutter_flickd_rest_app architecture

> Architecture diagram of the GitHub repository josedev155/flutter_flickd_rest_app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/josedev155/flutter_flickd_rest_app
- Repository: https://github.com/josedev155/flutter_flickd_rest_app

## Overview

##### What this project is (type + purpose)

It is a **single codebase** deployed to **Android, iOS, and Web** (see `android/`, `ios/`, `web/`), with the core app in `lib/` using a fairly standard layered structure:
- **UI**: `pages/`, `widgets/`
- **State/coordination**: `controllers/`
- **Domain/data models**: `models/`
- **Networking/data access**: `services/`

##### The key runtime relationships to show (what talks to what)

**User Interaction**
→ `pages/main_page.dart` + `widgets/movie_tile.dart` (presentation)
→ `controllers/main_page_data_controller.dart` (state + orchestration)
→ `services/movie_service.dart` (use-case/data service)
→ `services/http_service.dart` (HTTP client)
→ **External Movie REST API** (unknown provider; represent generically)
→ JSON responses
→ `models/*.dart` (parse/deserialize to `Movie`, `MainPageData`, etc.)
→ controller updates state
→ UI re-renders

Also show:
- `lib/main.dart` initializes app, loads `AppConfig`, routes to `SplashPage` then `MainPage`.
- Assets (`assets/images`) are read by UI widgets/pages (one-way dependency).

##### Entry / App Bootstrap
- `main.dart`
- depends on: `pages/`, `models/app_config.dart`

##### Controller / State Layer
- `controllers/main_page_data_controller.dart`
- depends on: `services/movie_service.dart`, `models/main_page_data.dart`, `models/search_category.dart`

##### Services / Data Access Layer
- `services/movie_service.dart`
- depends on: `services/http_service.dart`, `models/movie.dart`, `models/search_category.dart`
- `services/http_service.dart`

##### Domain Models
- `models/movie.dart`
- `models/main_page_data.dart`
- `models/search_category.dart`
- `models/app_config.dart`

##### Assets
- `assets/images/*` (consumed by pages/widgets)

- **Movie REST API**
- Endpoints (if known), auth (API key), response types

- pages/widgets → controller (not the other way)
- controller → movie_service → http_service → external API
- services → models (for serialization)
- UI → assets

##### Architectural patterns/design principles to highlight (based on structure)
Even without full code, the directory layout strongly suggests:
- **Layered architecture** (UI → controller → services → external API)
- **Separation of concerns**
- UI components in `pages/` and `widgets/`
- Business/data orchestration in `controllers/`
- API access isolated in `services/`
- Data contracts in `models/`

##### render `MainPage` with list of `MovieTile`

UI event → controller → service → http → API → models → controller → UI

- `main.dart`
- `pages/splash_page.dart`
- `pages/main_page.dart`
- `widgets/movie_tile.dart`
- `controllers/main_page_data_controller.dart`
- `services/movie_service.dart`
- `services/http_service.dart`
- `models/app_config.dart`
- `models/main_page_data.dart`
- `models/movie.dart`
- `models/search_category.dart`
- `assets/images`
- External: Movie REST API
- Deployment shells: Android / iOS / Web

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% =========================================================
    %% Level 1 — System Context
    %% =========================================================
    subgraph "Level 1: System Context"
        U["Mobile/Web User"]:::actor
        SYS["Flickd Flutter App\n(Client-only movie browsing UI)"]:::system
        API["External Movie REST API\n(HTTPS JSON)"]:::external
        CDN["Optional: Image CDN\n(Poster URLs)"]:::external
    end

    U -->|"browse/search_movies"| SYS
    SYS -->|"fetch_movie_lists/details"| API
    SYS -->|"load_poster_images"| CDN

    %% =========================================================
    %% Level 2 — Containers (Deployment / Runtime)
    %% =========================================================
    subgraph "Level 2: Containers"
        subgraph "Device / Browser"
            AND["Android Shell\n(android/)"]:::platform
            IOS["iOS Shell\n(ios/)"]:::platform
            WEB["Web Shell\n(web/)"]:::platform

            subgraph "Flutter Runtime + Dart Code"
                APP["Flutter App (Dart)\n(lib/)"]:::container
            end
        end

        subgraph "External Internet Services"
            EXTAPI["Movie REST API\n(External)"]:::external
        end
    end

    U -->|"touch/click/input"| AND
    U -->|"touch/gesture/input"| IOS
    U -->|"mouse/keyboard/input"| WEB

    AND -->|"hosts"| APP
    IOS -->|"hosts"| APP
    WEB -->|"hosts"| APP

    APP -->|"HTTPS_requests"| EXTAPI
    EXTAPI -->|"JSON_responses"| APP

    %% =========================================================
    %% Level 3 — Components (lib/ architecture)
    %% =========================================================
    subgraph "Level 3: Component Diagram — Flutter App (lib/)"
        subgraph "Entry / App Bootstrap"
            MAIN["lib/main.dart\nEntrypoint + routing\n(load AppConfig, show Splash -> Main)"]:::bootstrap
            CFG["models/app_config.dart\nAppConfig (API base URL/key/etc.)"]:::model
        end

        subgraph "Presentation Layer (UI)"
            SPLASH["pages/splash_page.dart\nInitial UX while loading/configuring"]:::ui
            MPAGE["pages/main_page.dart\nMain screen (feed + search/filter)"]:::ui
            MTILE["widgets/movie_tile.dart\nReusable Movie tile widget"]:::ui
            ASSETS["assets/images/*\nStatic images"]:::assets
        end

        subgraph "Controller / State Layer"
            CTRL["controllers/main_page_data_controller.dart\nState + orchestration\n(load, search, category)"]:::controller
        end

        subgraph "Services / Data Access Layer"
            MSVC["services/movie_service.dart\nMovieService (domain API methods)"]:::service
            HSVC["services/http_service.dart\nHttpService (HTTP wrapper,\nbase URL/headers/errors)"]:::service
            HTTPLIB["HTTP Library\n(dart:io / package:http)"]:::lib
        end

        subgraph "Domain Models"
            MPMODEL["models/main_page_data.dart\nMainPageData (aggregate view-model)"]:::model
            MOVIE["models/movie.dart\nMovie entity"]:::model
            CAT["models/search_category.dart\nSearch/filter category model"]:::model
        end

        PUB["pubspec.yaml\nAssets registration + dependencies"]:::config
    end

    %% Bootstrap flow
    MAIN -->|"loads_config"| CFG
    MAIN -->|"routes_to"| SPLASH
    SPLASH -->|"navigates_to"| MPAGE

    %% UI composition & assets usage
    MPAGE -->|"composes_list_item"| MTILE
    MPAGE -->|"reads_static_images"| ASSETS
    MTILE -->|"reads_static_images"| ASSETS
    PUB -->|"registers_assets"| ASSETS

    %% UI -> Controller (events/intents)
    MPAGE -->|"events:intents\n(search/refresh/select_category)"| CTRL

    %% Controller -> Services
    CTRL -->|"getMainPageData(category,query)"| MSVC
    CTRL -->|"uses_models"| MPMODEL
    CTRL -->|"uses_category"| CAT

    %% Services -> HTTP -> External API
    MSVC -->|"build_requests\n(fetch/search/categories)"| HSVC
    MSVC -->|"parses_to"| MOVIE
    MSVC -->|"uses_category"| CAT
    HSVC -->|"uses"| HTTPLIB
    HSVC -->|"HTTPS_JSON"| EXTAPI
    EXTAPI -->|"JSON"| HSVC

    %% Data returned upward (modeled as annotated return edges)
    HSVC -->|"responses"| MSVC
    MSVC -->|"maps_to_models\n(Movie/MainPageData)"| MPMODEL
    MSVC -->|"maps_to_models"| MOVIE
    MSVC -->|"returns_data"| CTRL
    CTRL -->|"state_updated\nnotify/rebuild"| MPAGE

    %% =========================================================
    %% Optional companion: Sequence — App start to main page
    %% =========================================================
    subgraph "Sequence A (optional): App start -> MainPage"
        SA1["1) lib/main.dart"]:::seq
        SA2["2) models/app_config.dart loaded"]:::seq
        SA3["3) pages/splash_page.dart shown"]:::seq
        SA4["4) controllers/main_page_data_controller.dart init"]:::seq
        SA5["5) services/movie_service.dart fetch"]:::seq
        SA6["6) services/http_service.dart GET (HTTPS)"]:::seq
        SA7["7) Movie REST API returns JSON"]:::seq
        SA8["8) models/main_page_data.dart parsed"]:::seq
        SA9["9) pages/main_page.dart renders + widgets/movie_tile.dart list"]:::seq

        SA1 --> SA2 --> SA3 --> SA4 --> SA5 --> SA6 --> SA7 --> SA8 --> SA9
    end

    %% Optional companion: Sequence — Search/change category
    subgraph "Sequence B (optional): Search / Change Category"
        SB1["1) pages/main_page.dart event\n(search/category)"]:::seq
        SB2["2) controllers/main_page_data_controller.dart"]:::seq
        SB3["3) services/movie_service.dart"]:::seq
        SB4["4) services/http_service.dart"]:::seq
        SB5["5) Movie REST API"]:::seq
        SB6["6) models parsed (Movie/MainPageData)"]:::seq
        SB7["7) controller updates state"]:::seq
        SB8["8) UI rebuilds"]:::seq

        SB1 --> SB2 --> SB3 --> SB4 --> SB5 --> SB6 --> SB7 --> SB8
    end

    %% =========================================================
    %% Click events (from component_mapping)
    %% =========================================================
    click AND "https://github.com/josedev155/flutter_flickd_rest_app/tree/master/android/"
    click IOS "https://github.com/josedev155/flutter_flickd_rest_app/tree/master/ios/"
    click WEB "https://github.com/josedev155/flutter_flickd_rest_app/tree/master/web/"
    click MAIN "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/main.dart"
    click SPLASH "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/pages/splash_page.dart"
    click MPAGE "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/pages/main_page.dart"
    click MTILE "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/widgets/movie_tile.dart"
    click CTRL "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/controllers/main_page_data_controller.dart"
    click HSVC "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/services/http_service.dart"
    click MSVC "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/services/movie_service.dart"
    click CFG "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/models/app_config.dart"
    click MPMODEL "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/models/main_page_data.dart"
    click MOVIE "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/models/movie.dart"
    click CAT "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/lib/models/search_category.dart"
    click ASSETS "https://github.com/josedev155/flutter_flickd_rest_app/tree/master/assets/images/"
    click PUB "https://github.com/josedev155/flutter_flickd_rest_app/blob/master/pubspec.yaml"

    %% =========================================================
    %% Styles
    %% =========================================================
    classDef actor fill:#111827,stroke:#111827,color:#ffffff,stroke-width:2px
    classDef system fill:#0b3b74,stroke:#062b55,color:#ffffff,stroke-width:2px
    classDef container fill:#1d4ed8,stroke:#0b3b74,color:#ffffff,stroke-width:2px
    classDef platform fill:#6b7280,stroke:#374151,color:#ffffff,stroke-width:2px
    classDef external fill:#ffffff,stroke:#b91c1c,color:#7f1d1d,stroke-width:3px
    classDef bootstrap fill:#0ea5e9,stroke:#075985,color:#ffffff,stroke-width:2px
    classDef ui fill:#2563eb,stroke:#1e40af,color:#ffffff,stroke-width:2px
    classDef controller fill:#7c3aed,stroke:#4c1d95,color:#ffffff,stroke-width:2px
    classDef service fill:#16a34a,stroke:#14532d,color:#ffffff,stroke-width:2px
    classDef model fill:#f59e0b,stroke:#92400e,color:#111827,stroke-width:2px
    classDef assets fill:#0f766e,stroke:#134e4a,color:#ffffff,stroke-width:2px
    classDef config fill:#334155,stroke:#0f172a,color:#ffffff,stroke-width:2px
    classDef lib fill:#22c55e,stroke:#166534,color:#052e16,stroke-width:2px
    classDef seq fill:#f1f5f9,stroke:#94a3b8,color:#0f172a,stroke-width:1px
```
