# zeiadd1310/movieverse---movie-explorer-app- architecture

> Architecture diagram of the GitHub repository zeiadd1310/movieverse---movie-explorer-app-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zeiadd1310/movieverse---movie-explorer-app-
- Repository: https://github.com/zeiadd1310/movieverse---movie-explorer-app-

## Overview

#### Purpose and Runtime
MovieVerse is a cross-platform Flutter/Dart movie explorer. It presents trending/searchable TMDB content, movie details and ratings, plus authenticated user watchlist/favorites flows. The Flutter app is the primary runtime; native launchers support Android, iOS, web, Linux, macOS, and Windows. Entry point: `lib/main.dart`.

#### Application Bootstrap and Navigation
Startup initializes shared application dependencies/providers and routes users through splash/authentication into the main experience. Router and app-flow utilities form the navigation/auth boundary, while the main layout hosts persistent feature navigation.
- `lib/main.dart`
- `lib/core/utils/functions/app_router.dart`
- `lib/features/layout/main_layout.dart`

#### Core Data and Service Boundary
Data access is organized around repository interfaces and implementations. Shared models, providers, failure types, and an API service centralize API-facing behavior rather than allowing views to call external services directly. TMDB is the movie-content REST dependency; Firebase configuration indicates Firebase-backed application services.
- `lib/core/utils/functions/api_service.dart`
- `lib/core/data/providers.dart`
- `lib/firebase_options.dart`

#### Authentication
The auth feature separates repository-backed identity operations from Cubit-driven presentation state and sign-in/sign-up/password-reset screens. Auth state controls access into the application flow.
- `lib/features/auth/data/repos/auth_repo.dart`
- `lib/features/auth/data/repos/auth_repo_impl.dart`
- `lib/features/auth/presentation/cubits/auth_cubit.dart`

#### Movie Discovery and Search
Home retrieves and presents movie/genre data, including trending content. Search is an independent vertical slice with its own movie model, repository contract/implementation, and Cubit state. Both follow the flow: view event → Cubit → repository → API service → state → rendered view.
- `lib/features/home/data/repos/home_repo_impl.dart`
- `lib/features/home/presentation/cubits/home_cubit.dart`
- `lib/features/search/data/repos/search_repo_impl.dart`

#### Details and Reviews
Selecting a movie enters the detail domain, which has dedicated detail and review repository layers and separate Cubits. This is the boundary for loading rich metadata and submitting or displaying ratings/reviews.
- `lib/features/movie_details/data/repos/movie_details_repo_imp.dart`
- `lib/features/movie_details/data/repos/review_repo_impl.dart`
- `lib/features/movie_details/presentation/cubits/movie_details_cubit.dart`

#### Personal Collections and Shared UI
Favorites and watchlist/watched screens provide user collection views; favorites has explicit Cubit state management. Reusable cards, headers, casts, ratings, bottom navigation, and form controls keep cross-feature rendering consistent. Local image assets support collection states.
- `lib/features/favourites/presentation/cubits/favorites_cubit.dart`
- `lib/features/watchlist/presentation/views/watchlist_view.dart`
- `lib/widgets/movie_card.dart`

#### Platform and Infrastructure
Flutter builds to native Android/iOS/desktop and web shells. Android includes Google services configuration, and root Firebase configuration supports deployment/service integration. Platform projects are generated host layers, not primary business logic.
- `android/app/google-services.json`
- `firebase.json`
- `web/index.html`

Main entry points: [`lib/core/utils/functions/api_service.dart`](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/utils/functions/api_service.dart) (API service), [`lib/features/layout/main_layout.dart`](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/layout/main_layout.dart) (Main layout), [`lib/main.dart`](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/main.dart) (Flutter entrypoint), [`lib/core/utils/functions/app_router.dart`](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/utils/functions/app_router.dart) (Router & auth flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_flutter_app["Flutter entrypoint<br/>Flutter runtime<br/>[main.dart]"]
  node_router["Router &amp; auth flow<br/>navigation boundary<br/>[app_router.dart]"]
  node_main_layout["Main layout<br/>feature navigation shell<br/>[main_layout.dart]"]
  node_shared_widgets["Shared movie UI<br/>reusable widgets<br/>[movie_card.dart]"]
end

subgraph group_features["Feature Domains"]
  node_auth_repo["Auth repository<br/>repository contract<br/>[auth_repo.dart]"]
  node_auth_repo_impl["Auth repository impl<br/>repository implementation"]
  node_auth_cubit["Auth Cubit<br/>presentation state<br/>[auth_cubit.dart]"]
  node_home_cubit["Home Cubit<br/>presentation state<br/>[home_cubit.dart]"]
  node_home_repo["Home repository<br/>repository implementation"]
  node_search_repo["Search repository<br/>repository implementation"]
  node_movie_details_cubit["Movie details Cubit<br/>presentation state"]
  node_details_repo["Details repository<br/>repository implementation"]
  node_review_repo["Review repository<br/>repository implementation"]
  node_favorites_cubit["Favorites Cubit<br/>collection state"]
  node_watchlist["Watchlist views<br/>collection UI"]
end

subgraph group_data["Data &amp; Services"]
  node_providers["Shared providers<br/>dependency state<br/>[providers.dart]"]
  node_api_service{{"API service<br/>service gateway<br/>[api_service.dart]"}}
  node_tmdb{{"TMDB API<br/>external REST API"}}
  node_firebase{{"Firebase services<br/>external backend"}}
end

subgraph group_platform["Platform Hosts"]
  node_platform_hosts["Native &amp; web hosts<br/>generated platform shells<br/>[index.html]"]
  node_android_services["Android Google services<br/>platform configuration"]
  node_firebase_deployment["Firebase deployment<br/>infrastructure configuration<br/>[firebase.json]"]
end

node_flutter_app -->|"initializes"| node_providers
node_flutter_app -->|"starts"| node_router
node_router -->|"checks auth state"| node_auth_cubit
node_router -->|"enters app"| node_main_layout
node_main_layout -->|"hosts"| node_home_cubit
node_main_layout -->|"hosts"| node_favorites_cubit
node_main_layout -->|"hosts"| node_watchlist
node_auth_cubit -->|"uses"| node_auth_repo
node_auth_repo_impl -.->|"implements"| node_auth_repo
node_auth_cubit -->|"auth operations"| node_auth_repo_impl
node_auth_repo_impl -->|"identity services"| node_firebase
node_home_cubit -->|"loads content"| node_home_repo
node_home_repo -->|"requests"| node_api_service
node_search_repo -->|"searches through"| node_api_service
node_movie_details_cubit -->|"loads details"| node_details_repo
node_details_repo -->|"requests"| node_api_service
node_review_repo -->|"submits and loads"| node_api_service
node_api_service -->|"REST calls"| node_tmdb
node_providers -->|"provides"| node_api_service
node_home_cubit -->|"renders with"| node_shared_widgets
node_movie_details_cubit -->|"reviews"| node_review_repo
node_flutter_app -.->|"builds for"| node_platform_hosts
node_android_services -.->|"configures"| node_firebase
node_firebase_deployment -.->|"deploys integration"| node_firebase

click node_flutter_app "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/main.dart"
click node_router "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/utils/functions/app_router.dart"
click node_main_layout "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/layout/main_layout.dart"
click node_providers "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/data/providers.dart"
click node_api_service "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/utils/functions/api_service.dart"
click node_firebase "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/firebase_options.dart"
click node_auth_repo "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/auth/data/repos/auth_repo.dart"
click node_auth_repo_impl "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/auth/data/repos/auth_repo_impl.dart"
click node_auth_cubit "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/auth/presentation/cubits/auth_cubit.dart"
click node_home_cubit "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/home/presentation/cubits/home_cubit.dart"
click node_home_repo "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/home/data/repos/home_repo_impl.dart"
click node_search_repo "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/search/data/repos/search_repo_impl.dart"
click node_movie_details_cubit "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/movie_details/presentation/cubits/movie_details_cubit.dart"
click node_details_repo "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/movie_details/data/repos/movie_details_repo_imp.dart"
click node_review_repo "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/movie_details/data/repos/review_repo_impl.dart"
click node_favorites_cubit "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/favourites/presentation/cubits/favorites_cubit.dart"
click node_watchlist "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/watchlist/presentation/views/watchlist_view.dart"
click node_shared_widgets "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/widgets/movie_card.dart"
click node_platform_hosts "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/web/index.html"
click node_android_services "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/android/app/google-services.json"
click node_firebase_deployment "https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/firebase.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_flutter_app,node_router,node_main_layout,node_shared_widgets toneBlue
class node_auth_repo,node_auth_repo_impl,node_auth_cubit,node_home_cubit,node_home_repo,node_search_repo,node_movie_details_cubit,node_details_repo,node_review_repo,node_favorites_cubit,node_watchlist toneAmber
class node_providers,node_api_service,node_tmdb,node_firebase toneMint
class node_platform_hosts,node_android_services,node_firebase_deployment toneRose
```

## Components

### App Shell

- [Flutter entrypoint](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/main.dart): Flutter runtime · Initializes providers and application startup. · `lib/main.dart`
- [Router & auth flow](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/utils/functions/app_router.dart): navigation boundary · Routes splash and authentication into the app. · `lib/core/utils/functions/app_router.dart`
- [Main layout](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/layout/main_layout.dart): feature navigation shell · Hosts persistent feature navigation. · `lib/features/layout/main_layout.dart`
- [Shared movie UI](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/widgets/movie_card.dart): reusable widgets · Provides common movie cards and controls. · `lib/widgets/movie_card.dart`

### Feature Domains

- [Auth repository](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/auth/data/repos/auth_repo.dart): repository contract · `lib/features/auth/data/repos/auth_repo.dart`
- [Auth repository impl](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/auth/data/repos/auth_repo_impl.dart): repository implementation · `lib/features/auth/data/repos/auth_repo_impl.dart`
- [Auth Cubit](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/auth/presentation/cubits/auth_cubit.dart): presentation state · Controls authenticated access. · `lib/features/auth/presentation/cubits/auth_cubit.dart`
- [Home Cubit](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/home/presentation/cubits/home_cubit.dart): presentation state · Loads trending movies and genres. · `lib/features/home/presentation/cubits/home_cubit.dart`
- [Home repository](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/home/data/repos/home_repo_impl.dart): repository implementation · `lib/features/home/data/repos/home_repo_impl.dart`
- [Search repository](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/search/data/repos/search_repo_impl.dart): repository implementation · Search vertical-slice data access. · `lib/features/search/data/repos/search_repo_impl.dart`
- [Movie details Cubit](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/movie_details/presentation/cubits/movie_details_cubit.dart): presentation state · Loads selected movie metadata. · `lib/features/movie_details/presentation/cubits/movie_details_cubit.dart`
- [Details repository](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/movie_details/data/repos/movie_details_repo_imp.dart): repository implementation · `lib/features/movie_details/data/repos/movie_details_repo_imp.dart`
- [Review repository](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/movie_details/data/repos/review_repo_impl.dart): repository implementation · Handles ratings and reviews. · `lib/features/movie_details/data/repos/review_repo_impl.dart`
- [Favorites Cubit](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/favourites/presentation/cubits/favorites_cubit.dart): collection state · Manages user favorites. · `lib/features/favourites/presentation/cubits/favorites_cubit.dart`
- [Watchlist views](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/features/watchlist/presentation/views/watchlist_view.dart): collection UI · Displays watchlist and watched collections. · `lib/features/watchlist/presentation/views/watchlist_view.dart`

### Data & Services

- [Shared providers](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/data/providers.dart): dependency state · Supplies shared application dependencies. · `lib/core/data/providers.dart`
- [API service](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/core/utils/functions/api_service.dart): service gateway · Centralizes API-facing behavior. · `lib/core/utils/functions/api_service.dart`
- **TMDB API**: external REST API · Movie and genre content source.
- [Firebase services](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/lib/firebase_options.dart): external backend · Supports configured application services. · `lib/firebase_options.dart`

### Platform Hosts

- [Native & web hosts](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/web/index.html): generated platform shells · Build targets for mobile, desktop, and web. · `web/index.html`
- [Android Google services](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/android/app/google-services.json): platform configuration · `android/app/google-services.json`
- [Firebase deployment](https://github.com/zeiadd1310/movieverse---movie-explorer-app-/blob/develop/firebase.json): infrastructure configuration · `firebase.json`

## Connections

- Flutter entrypoint → Shared providers: initializes
- Flutter entrypoint → Router & auth flow: starts
- Router & auth flow → Auth Cubit: checks auth state
- Router & auth flow → Main layout: enters app
- Main layout → Home Cubit: hosts
- Main layout → Favorites Cubit: hosts
- Main layout → Watchlist views: hosts
- Auth Cubit → Auth repository: uses
- Auth repository impl → Auth repository: implements
- Auth Cubit → Auth repository impl: auth operations
- Auth repository impl → Firebase services: identity services
- Home Cubit → Home repository: loads content
- Home repository → API service: requests
- Search repository → API service: searches through
- Movie details Cubit → Details repository: loads details
- Details repository → API service: requests
- Review repository → API service: submits and loads
- API service → TMDB API: REST calls
- Shared providers → API service: provides
- Home Cubit → Shared movie UI: renders with
- Movie details Cubit → Review repository: reviews
- Flutter entrypoint → Native & web hosts: builds for
- Android Google services → Firebase services: configures
- Firebase deployment → Firebase services: deploys integration