# alleylopez/alley-planets architecture

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

- Interactive diagram: https://gitdiagram.com/alleylopez/alley-planets
- Repository: https://github.com/alleylopez/alley-planets

## Overview

##### Project type and purpose
- **Type**: Multi-platform Flutter application (mobile, web, desktop).
- **Purpose**: Display and filter “planet” data; fetch and store data in Cloud Firestore; local caching/favourites; navigation via deep links; planned educational-game extension.

##### File structure
- **Platform folders**: `android/`, `ios/`, `linux/`, `macos/`, `windows/`, `web/` → Flutter embedder and build artifacts/hosted assets.
- **Shared client code**: `lib/` → organizes code into `core/` and `features/planets/` by Clean-architecture layers (presentation, application, domain, data, facade).
- **Configuration**: `pubspec.yaml`, `firebase.json`, `.firebaserc`, Firestore rules/indexes.

##### README
- **Stack**: Flutter, Riverpod (state management & DI), Firebase (Hosting for web, Firestore for data).
- **Architecture mention**: Appreciation of Riverpod usage suggests provider-based dependency injection and reactive state.

##### Main components
a. **Flutter Client (Multi-Platform)**
- Subdivide into **Presentation Layer** (`lib/features/planets/presentation/...`)
- Screens & Widgets (e.g., `HomeScreen`, `PlanetScreen`, filter bar, glowing buttons)
- **Application Layer** (`lib/features/planets/application/...`)
- Controllers (Riverpod state notifiers & providers)
- Routing (AppRouter via go_router or similar)
- **Domain Layer** (`lib/features/planets/domain/...`)
- Entities (`Planet`)
- Interfaces/abstractions (e.g., `PlanetRepository` facade)
- **Data Layer** (`lib/features/planets/data/...`)
- DataSources (local via SharedPreferences / future, remote via Firestore)
- Repository implementations (`PlanetRepositoryImpl`)
b. **External Services & Infrastructure**
- **Cloud Firestore** (persistent, remote data store for planet documents & assets)
- **Firebase Hosting** (web artefacts, Canvaskit, assets)
- **Local Storage** (planned: SharedPreferences for favourites)
- **Asset Store** (packaged images under `assets/planets` also uploaded to Firestore)

##### Relationships & interactions
- **User → UI**: Tap/filter events in Screens/Widgets.
- **UI → Controller**: UI widgets invoke Riverpod controllers/notifiers.
- **Controller → Repository**: Controllers request data or actions via `PlanetRepository` interface.
- **Repository → DataSources**: Implementation chooses between local cache or Firestore.
- **Firestore ↔ Repository**: Async reads/writes of planet documents.
- **Router**: Intercepts deep-link URLs → navigates to appropriate Screen.

##### Architectural patterns & design principles
- **Clean Architecture**: Layered separation of concerns, domain-agnostic entities, dependency inversion via repository interfaces.
- **Riverpod**: Compile-safe DI & reactive state management.
- **Platform abstraction**: Flutter engine + platform embedder for Android/iOS/Web/Desktop.

##### Technologies, frameworks, libraries
- **Flutter SDK** + Dart
- **Riverpod** (state + DI)
- **go_router** or similar for deep linking/routing
- **Firebase Core / Firestore**
- **SharedPreferences** (planned)
- **Canvaskit** (for high-performance Web rendering)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Flutter Client"
        subgraph "Presentation Layer"
            HomeScreen["HomeScreen"] 
            PlanetsScreen["PlanetsScreen"]
            PlanetScreen["PlanetScreen"]
            GlowingButton["GlowingButton"]
            PlanetFilterBar["PlanetFilterBar"]
        end
        subgraph "Application Layer"
            PlanetFilterController["PlanetFilterController"]
            PlanetFilterState["PlanetFilterState"]
            PlanetRepositoryProvider["PlanetRepositoryProvider"]
            AppRouter["AppRouter"]
        end
        subgraph "Domain Layer"
            PlanetEntity["Planet Entity"]
            PlanetRepository["PlanetRepository Interface"]
        end
        subgraph "Data Layer"
            PlanetLocalDataSource["PlanetLocalDataSource"]
            PlanetRepositoryImpl["PlanetRepositoryImpl"]
        end
        subgraph "Core Utilities & Theming"
            AppTheme["AppTheme"]
            AppLogger["AppLogger"]
        end
    end

    subgraph "Assets"
        PlanetAssets["Planet Assets"]
        Fonts["Fonts"]
    end

    subgraph "External Services"
        Firestore[(Cloud Firestore)]
        FirebaseHosting[(Firebase Hosting)]
        SharedPreferences[(SharedPreferences)]
    end

    %% UI to Controllers
    HomeScreen -->|"user tap"| PlanetFilterController
    PlanetsScreen -->|"user tap/filter"| PlanetFilterController
    PlanetScreen -->|"user view"| PlanetFilterController
    GlowingButton -->|"onPressed"| PlanetFilterController
    PlanetFilterBar -->|"onInput"| PlanetFilterController

    %% Controllers to Providers & State
    PlanetFilterController -->|"updates state"| PlanetFilterState
    PlanetFilterController -->|"uses provider"| PlanetRepositoryProvider
    PlanetFilterState --> PlanetRepositoryProvider

    %% Routing
    AppRouter -->|"deep link"| PlanetScreen
    AppRouter -->|"deep link"| HomeScreen

    %% Providers to Domain
    PlanetRepositoryProvider -->|"provides"| PlanetRepository

    %% Domain to Data
    PlanetRepository -->|"implemented by"| PlanetRepositoryImpl
    PlanetRepositoryImpl -->|"uses"| PlanetLocalDataSource
    PlanetRepositoryImpl -->|"uses"| Firestore

    %% Data Sources
    PlanetLocalDataSource -->|"cache read/write"| SharedPreferences
    PlanetRepositoryImpl -->|"Firestore REST/gRPC"| Firestore

    %% Assets & Theming
    PlanetAssets --> HomeScreen
    Fonts --> HomeScreen
    AppTheme --> HomeScreen
    AppLogger --> PlanetFilterController

    %% Click Events
    click HomeScreen "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/presentation/screens/home_screen.dart"
    click PlanetsScreen "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/presentation/screens/planets_screen.dart"
    click PlanetScreen "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/presentation/screens/planet_screen.dart"
    click GlowingButton "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/presentation/widgets/glowing_button.dart"
    click PlanetFilterBar "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/presentation/widgets/planet_filter_bar.dart"
    click PlanetFilterController "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/application/controllers/planet_filter_controller.dart"
    click PlanetFilterState "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/application/controllers/planet_filter_state.dart"
    click PlanetRepositoryProvider "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/application/providers/planet_repository_provider.dart"
    click AppRouter "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/application/routing/app_router.dart"
    click PlanetEntity "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/domain/entities/planet.dart"
    click PlanetRepository "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/facade/planet_repository.dart"
    click PlanetLocalDataSource "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/data/datasources/planet_local_datasource.dart"
    click PlanetRepositoryImpl "https://github.com/alleylopez/alley-planets/blob/master/lib/features/planets/data/repositories/planet_repository_impl.dart"
    click AppTheme "https://github.com/alleylopez/alley-planets/blob/master/lib/core/theme/app_theme.dart"
    click AppLogger "https://github.com/alleylopez/alley-planets/blob/master/lib/core/utils/app_logger.dart"

    classDef presentation fill:#ADD8E6,stroke:#000;
    classDef application fill:#90EE90,stroke:#000;
    classDef domain fill:#FFFFE0,stroke:#000;
    classDef data fill:#FFDAB9,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;

    class HomeScreen,PlanetsScreen,PlanetScreen,GlowingButton,PlanetFilterBar presentation;
    class PlanetFilterController,PlanetFilterState,PlanetRepositoryProvider,AppRouter application;
    class PlanetEntity,PlanetRepository domain;
    class PlanetLocalDataSource,PlanetRepositoryImpl data;
    class Firestore,FirebaseHosting,SharedPreferences,PlanetAssets,Fonts external;
```
