# sonujoji/movie_explorer architecture

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

- Interactive diagram: https://gitdiagram.com/sonujoji/movie_explorer
- Repository: https://github.com/sonujoji/movie_explorer

## Overview

##### Project type & purpose (from file tree + README)
This is a **Flutter cross‑platform client application** (mobile + desktop + web targets). The README is the default scaffold, but the `lib/` structure clearly indicates the app’s purpose: a **Movie Explorer UI** that:
- renders multiple screens (home, movie, TV shows, search, details, trailer)
- calls an external movies API via `lib/service/api_service.dart`
- uses shared UI widgets (`movie_card`, `search_results`, etc.)
- uses constants/config in `lib/constants/constants.dart`
- defines domain models in `lib/models/model.dart`

There is **no backend service in this repo**; the “backend” is an **external 3rd‑party API** that the Flutter app calls directly.

##### Platform shells (deployment/runtime containers)
Top-level directories:
- `android/`, `ios/`, `macos/`, `windows/`, `linux/`, `web/`

`lib/` is the true “system”:
- `lib/main.dart` — app entrypoint, root `MaterialApp`/routing (likely)
- `lib/screens/**` — presentation/pages:
- `main_screen.dart`
- `main_screens/home_screen.dart`, `movie_screen.dart`, `tv_shows_screen.dart`, `search_screen.dart`
- `movie_category_screen.dart`, `movie_details_screen.dart`, `trailer_screen.dart`
- `lib/widgets/**` — reusable UI components
- `lib/service/api_service.dart` — network boundary to external API
- `lib/models/model.dart` — data models/entities (movie/TV/search result)
- `lib/constants/constants.dart` — base URL, API key name, endpoints, etc.

This strongly suggests a **client-only layered architecture**:
- UI (screens/widgets)
- domain/data models
- service layer (API client)

(There’s no explicit `repository/`, `bloc/`, `provider/`, `state/` folders shown; so keep state management as “in-screen/stateful” unless you confirm otherwise.)

##### Client app (Flutter)
**Component group: “Movie Explorer Flutter App”**
- **Entry / App Shell**
- `main.dart` (bootstraps app, theme, navigation)
- **Navigation / Routing**
- implied from `main_screen.dart` + the multiple screens (show this as a router / navigator)
- **Presentation Layer (Screens)**
- Main Screen
- Home Screen
- Movie Screen
- TV Shows Screen
- Search Screen
- Movie Category Screen
- Movie Details Screen
- Trailer Screen
- **UI Components (Widgets)**
- MovieCard
- SearchResults
- TopSearchIdle
- **Data/Domain**
- Models (`model.dart`)
- Constants (`constants.dart`)
- **Integration Layer**
- API Service (`api_service.dart`) — HTTP client, request building, JSON parsing

##### External dependencies
Because there is no internal server:
- **External Movie/TV API** (label it explicitly; if it’s TMDB or similar, name it once confirmed)
- **(Optional) Trailer Provider**
- If `trailer_screen.dart` plays trailers via YouTube/Vimeo or opens external links, show “External Video Provider” as a separate external system (even if it’s just a web URL).

##### Platform/runtime
As deployment targets (not core logic):
- Android Runner (Kotlin `MainActivity.kt`)
- iOS Runner (Swift `AppDelegate.swift`)
- Web hosting (static site hosting `web/index.html`, `manifest.json`)
- Desktop runners (Windows/Linux/macOS)

These runners all point to the same Flutter bundle.

##### Navigation flow
- **MainScreen / Navigator** → routes to → (Home/Movie/TV/Search/Details/Trailer)

##### Trailer flow (if applicable)
- **TrailerScreen** → opens/embeds → **External Video Provider** (or **WebView / URL launcher** plugin, if used—confirm via `pubspec.yaml`)

##### Architectural patterns/principles to highlight
Tailor these callouts to what’s visible:
- **Layering**: Presentation (`screens`, `widgets`) vs Integration (`service`) vs Domain (`models`) vs Config (`constants`)
- **Single codebase, multi-platform deployment**: same `lib/` deployed to Android/iOS/Web/Desktop via platform runners
- **API boundary**: `ApiService` is the main seam; this is where auth keys, endpoints, and error handling should be encapsulated
- **Model mapping**: `model.dart` defines the contract between remote JSON and UI rendering

If the engineer wants “most accurate,” encourage them to inspect:
- `api_service.dart` for endpoints, pagination, caching, error handling, rate limit logic
- `pubspec.yaml` for dependencies (http/dio, state mgmt, video player, caching, etc.)
- `main.dart` for routing/state patterns

**Actors & external systems**
- User
- Movie Explorer App
- External Movie API
- External Trailer/Video Provider (if used)

**How it runs on platforms**
- Flutter App (single container)
- Deployed to: Android/iOS/Web/Desktop
- External API over HTTPS

**Inside Flutter app**
- main.dart (bootstrap + navigation)
- screens (each as a component)
- widgets
- api_service
- models/constants

- **Screens** (`lib/screens/...`)
- **Widgets** (`lib/widgets/...`)
- **Service** (`lib/service/api_service.dart`)
- **Models** (`lib/models/model.dart`)
- **Constants** (`lib/constants/constants.dart`)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Actors / Systems
  %% =========================
  User["User"]:::actor
  MovieAPI["ExternalMovie/TVAPI\n(HTTPSJSON)"]:::external
  VideoProvider["ExternalVideoProvider\n(YouTube/Vimeo/etc.)"]:::external

  %% =========================
  %% Deployment Targets (Runners)
  %% =========================
  subgraph "DeploymentTargets (FlutterPlatformRunners)"
    direction TB
    AndroidRunner["AndroidRunner\n(android/)"]:::runner
    IOSRunner["iOSRunner\n(ios/)"]:::runner
    MacRunner["macOSRunner\n(macos/)"]:::runner
    LinuxRunner["LinuxRunner\n(linux/)"]:::runner
    WindowsRunner["WindowsRunner\n(windows/)"]:::runner
    WebRunner["WebShell\n(web/)"]:::runner
  end

  %% =========================
  %% In-Repo System Boundary
  %% =========================
  subgraph "MovieExplorerFlutterApp (in-repo)"
    direction TB

    LibRoot["lib/ (CoreAppCode)"]:::boundary

    subgraph "AppShell"
      direction TB
      MainDart["main.dart\n(AppEntrypointBootstrap)"]:::app
      Navigator["Navigator/Router\n(MaterialAppRoutes)"]:::nav
      MainScreen["MainScreen\n(Tab/RouterHost)"]:::screen
    end

    subgraph "PresentationLayer: Screens"
      direction TB
      ScreensDir["screens/"]:::boundary

      subgraph "MainScreens"
        direction TB
        HomeScreen["HomeScreen"]:::screen
        MovieScreen["MovieScreen"]:::screen
        TVShowsScreen["TVShowsScreen"]:::screen
        SearchScreen["SearchScreen"]:::screen
      end

      MovieCategoryScreen["MovieCategoryScreen"]:::screen
      MovieDetailsScreen["MovieDetailsScreen"]:::screen
      TrailerScreen["TrailerScreen"]:::screen
    end

    subgraph "UIComponents: Widgets"
      direction TB
      WidgetsDir["widgets/"]:::boundary
      MovieCard["MovieCard"]:::widget
      SearchResults["SearchResults"]:::widget
      TopSearchIdle["TopSearchIdle"]:::widget
    end

    subgraph "IntegrationLayer"
      direction TB
      ApiService["ApiService\n(HTTPClientBoundary)"]:::service
    end

    subgraph "DomainAndConfig"
      direction TB
      Models["Models\n(model.dart)"]:::domain
      Constants["Constants\n(constants.dart)"]:::config
    end
  end

  %% =========================
  %% Deployment Wiring
  %% =========================
  AndroidRunner -->|"boots"| MainDart
  IOSRunner -->|"boots"| MainDart
  MacRunner -->|"boots"| MainDart
  LinuxRunner -->|"boots"| MainDart
  WindowsRunner -->|"boots"| MainDart
  WebRunner -->|"loads"| MainDart

  %% =========================
  %% Primary Runtime Flow
  %% =========================
  User -->|"taps/types"| MainScreen
  User -->|"navigates"| Navigator

  MainDart -->|"configures(theme/routes)"| Navigator
  MainDart -->|"setsHome"| MainScreen

  MainScreen -->|"NavigatorPush/Pop"| Navigator
  Navigator -->|"routesTo"| HomeScreen
  Navigator -->|"routesTo"| MovieScreen
  Navigator -->|"routesTo"| TVShowsScreen
  Navigator -->|"routesTo"| SearchScreen
  Navigator -->|"routesTo"| MovieCategoryScreen
  Navigator -->|"routesTo"| MovieDetailsScreen
  Navigator -->|"routesTo"| TrailerScreen

  %% UI composition
  HomeScreen -->|"composeUI"| MovieCard
  MovieScreen -->|"composeUI"| MovieCard
  TVShowsScreen -->|"composeUI"| MovieCard
  SearchScreen -->|"composeUI"| TopSearchIdle
  SearchScreen -->|"composeUI"| SearchResults
  MovieCategoryScreen -->|"composeUI"| MovieCard
  MovieDetailsScreen -->|"composeUI"| MovieCard

  %% Data fetching
  HomeScreen -->|"requestData()"| ApiService
  MovieScreen -->|"requestData()"| ApiService
  TVShowsScreen -->|"requestData()"| ApiService
  SearchScreen -->|"search(query)"| ApiService
  MovieCategoryScreen -->|"requestCategory()"| ApiService
  MovieDetailsScreen -->|"getDetails(id)"| ApiService
  TrailerScreen -->|"getTrailer(id)"| ApiService

  ApiService -->|"uses"| Constants
  ApiService -->|"deserialize/map"| Models

  ApiService -->|"HTTPS"| MovieAPI
  MovieAPI -.->|"JSONresponse"| ApiService
  ApiService -.->|"models"| HomeScreen
  ApiService -.->|"models"| MovieScreen
  ApiService -.->|"models"| TVShowsScreen
  ApiService -.->|"models"| SearchScreen
  ApiService -.->|"models"| MovieCategoryScreen
  ApiService -.->|"models"| MovieDetailsScreen
  ApiService -.->|"models"| TrailerScreen

  %% Trailer flow (optional external provider)
  TrailerScreen -->|"open/embed(trailerUrl)"| VideoProvider

  %% Anchors to show folder ownership ties
  LibRoot --> MainDart
  LibRoot --> ScreensDir
  LibRoot --> WidgetsDir
  LibRoot --> ApiService
  LibRoot --> Models
  LibRoot --> Constants
  ScreensDir --> MainScreen

  %% =========================
  %% Click Events (from mapping)
  %% =========================
  click LibRoot "https://github.com/sonujoji/movie_explorer/tree/master/lib/"
  click MainDart "https://github.com/sonujoji/movie_explorer/blob/master/lib/main.dart"
  click MainScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/main_screen.dart"
  click ScreensDir "https://github.com/sonujoji/movie_explorer/tree/master/lib/screens/"
  click HomeScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/main_screens/home_screen.dart"
  click MovieScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/main_screens/movie_screen.dart"
  click TVShowsScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/main_screens/tv_shows_screen.dart"
  click SearchScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/main_screens/search_screen.dart"
  click MovieCategoryScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/movie_category_screen.dart"
  click MovieDetailsScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/movie_details_screen.dart"
  click TrailerScreen "https://github.com/sonujoji/movie_explorer/blob/master/lib/screens/trailer_screen.dart"
  click WidgetsDir "https://github.com/sonujoji/movie_explorer/tree/master/lib/widgets/"
  click MovieCard "https://github.com/sonujoji/movie_explorer/blob/master/lib/widgets/movie_card.dart"
  click SearchResults "https://github.com/sonujoji/movie_explorer/blob/master/lib/widgets/search_results.dart"
  click TopSearchIdle "https://github.com/sonujoji/movie_explorer/blob/master/lib/widgets/top_search_idle.dart"
  click ApiService "https://github.com/sonujoji/movie_explorer/blob/master/lib/service/api_service.dart"
  click Models "https://github.com/sonujoji/movie_explorer/blob/master/lib/models/model.dart"
  click Constants "https://github.com/sonujoji/movie_explorer/blob/master/lib/constants/constants.dart"
  click AndroidRunner "https://github.com/sonujoji/movie_explorer/tree/master/android/"
  click IOSRunner "https://github.com/sonujoji/movie_explorer/blob/master/ios/Runner/AppDelegate.swift"
  click MacRunner "https://github.com/sonujoji/movie_explorer/blob/master/macos/Runner/AppDelegate.swift"
  click LinuxRunner "https://github.com/sonujoji/movie_explorer/blob/master/linux/main.cc"
  click WindowsRunner "https://github.com/sonujoji/movie_explorer/blob/master/windows/runner/main.cpp"
  click WebRunner "https://github.com/sonujoji/movie_explorer/blob/master/web/index.html"

  %% =========================
  %% Styles
  %% =========================
  classDef actor fill:#111827,stroke:#111827,color:#ffffff,stroke-width:1px
  classDef external fill:#f3f4f6,stroke:#6b7280,color:#111827,stroke-width:1px,stroke-dasharray: 4 3
  classDef runner fill:#ffffff,stroke:#94a3b8,color:#0f172a,stroke-width:1px
  classDef boundary fill:#ecfeff,stroke:#0891b2,color:#0f172a,stroke-width:1px
  classDef app fill:#ede9fe,stroke:#6d28d9,color:#111827,stroke-width:1px
  classDef nav fill:#fae8ff,stroke:#a21caf,color:#111827,stroke-width:1px
  classDef screen fill:#dbeafe,stroke:#2563eb,color:#0f172a,stroke-width:1px
  classDef widget fill:#e0f2fe,stroke:#0284c7,color:#0f172a,stroke-width:1px
  classDef service fill:#ffedd5,stroke:#f97316,color:#111827,stroke-width:2px
  classDef domain fill:#dcfce7,stroke:#16a34a,color:#0f172a,stroke-width:1px
  classDef config fill:#d1fae5,stroke:#10b981,color:#0f172a,stroke-width:1px
```
