How alleylopez/alley-planets works
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)