Imported from AbdallahRehab/weatherly (AGENTS.md). Install upstream with npx skills add AbdallahRehab/weatherly. Copyright stays with the author.

Agent guide — weatherly

Project

weatherly — Weatherly is a lightweight Flutter weather application that allows users to search for real-time weather information by city name. Built with Clean Architecture principles and Bloc for state management, the app fetches live data from WeatherAPI, displaying current temperature, weather conditions, and corresponding icons in a responsive, modular UI. It handles network and input errors gracefully, and supports offline access through local caching of the last successful weather query.

Generated by FlutterInit. Package: com.example.weatherly.

Stack

Architecture (clean)

lib/src/
├── features/<feature>/
│   ├── data/          # datasources, models, repository impls
│   ├── domain/        # entities, repo contracts, use cases
│   └── presentation/  # screens, widgets, state (bloc)
├── routing/
├── services/
├── shared/
└── theme/

Rules

• domain/ is pure Dart — no Flutter imports, no imports from data/.
• data/ implements contracts from domain/ — never the reverse.
• Entities are not models — no fromJson/toJson on domain entities.
• Use cases expose a single responsibility (typically one public call()).
• presentation/ talks to use cases or state layer — not datasources directly.

State management (bloc)

• Events and states are immutable — prefer const constructors.
• BlocBuilder for UI rebuilds; BlocListener for side effects; BlocConsumer when both are needed.
• Keep handlers thin — delegate to use cases, repositories, or services.
• One bloc per feature flow — do not share blocs across unrelated features.

Navigation

• All routes are defined in lib/src/routing/app_router.dart — do not scatter route tables elsewhere.
• Prefer typed/named routes from the central config — avoid hard-coded path strings in widgets when a named route exists.
• context.go() replaces the stack; context.push() pushes on top.
• Redirects and guards belong in the router configuration, not inside individual screens.

Backend (custom)

• HTTP/Dio client is configured in lib/src/config/app_config.dart.
• API calls belong in lib/src/services/ (e.g. auth service) using the shared client.
• Base URL comes from environment / config — see SETUP.md.

For console setup (keys, native files, env), follow SETUP.md — do not duplicate platform steps here.

Networking

• Use the shared Dio instance from lib/src/config/app_config.dart — never Dio() inside a widget or screen.
• Extend or use existing services under lib/src/services/ for HTTP calls.
• Map transport errors to Failure / FutureEither results via runTask() — do not leak raw DioException to UI.

Services & shared conventions

• Services are singletons with ClassName.instance, returning FutureEither<T> via runTask().
• Never pass BuildContext into services — use rootContext from the global navigator helper when UI is required.
• Logging: AppLogger; user feedback: showGlobalToast(); dialogs: showAppDialog() / context.showAppDialog().
• Primary import barrel: package:weatherly/src/imports/imports.dart.
• File names: snake_case.dart; classes: PascalCase; private members: _camelCase.
• Prefer const constructors where possible; avoid dynamic without justification.
• No empty catch blocks — log, map to failure, or rethrow.
• Do not add packages that duplicate existing stack choices (routing, state, backend).

Dart / Flutter anti-patterns

• No business logic in widget build() methods.

• No direct backend or network calls from presentation widgets.

• Do not put heavy logic inside bloc event handlers — delegate outward.

Key packages

• go_router — declarative routing

• flutter_bloc — state management

• dio

• shared_preferences

• flutter_secure_storage

• cached_network_image

• geolocator

• easy_localization

• flutter_screenutil

• flutter_hooks

• flutter_dotenv

• skeletonizer

How to add a new feature

1. Create domain entity and repository contract under lib/src/features/<feature>/domain/.
2. Add use case(s) in domain/usecases/ (single responsibility).
3. Add data model, datasource, and repository implementation under data/.
4. Wire state (bloc) under presentation/.
5. Build screens and widgets under presentation/.
6. Register the route in lib/src/routing/app_router.dart.
7. Export new public API only through existing barrel files if needed.

Safe to modify

| lib/src/shared/widgets/** | Reusable UI components | | lib/src/shared/helpers/** | App-wide helpers (when not generated-only) | | test/** | Unit and widget tests | | README.md | Project documentation |

Modify with caution

Do not touch

Verification after changes

flutter pub get
flutter analyze

Code generation

No build_runner step is required for the selected stack.

Localization

After editing assets/translations/*.json:

flutter pub run easy_localization:generate -S assets/translations -O lib/src/core/i18n -o locale_keys.g.dart

flutter test

Hard limits

• Do not disable flutter_lints rules without an explanatory comment.
• Do not call backend or networking code directly from widgets.
• Do not commit .env files containing production secrets.
• Do not introduce a second state-management or routing library.
• For platform setup and API keys, use SETUP.md.
• For UI tokens and spacing, use DESIGN.md.