Skip to content

Commit 9a1bfe9

Browse files
amaury901130amaury901130
authored
setup ai rules and env (#103)
1 parent e429fed commit 9a1bfe9

File tree

8 files changed

+355
-3
lines changed

8 files changed

+355
-3
lines changed

‎.cursor/rules/agent_rule.mdc‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: true
5+
---
6+
---
7+
description: Architectural rules for a Flutter project using Bloc Cubit
8+
globs: ["**/*.dart"]
9+
alwaysApply: true
10+
---
11+
12+
## description: |
13+
You are a senior Flutter engineer working on a modular Flutter project. The codebase follows a layered architecture with the following directory structure:
14+
15+
- `/app/lib/`: Main application layer (presentation widgets, navigation, routing).
16+
- `/modules/domain/lib/`: Core business logic (entities, services, cubits, states).
17+
- `/modules/data/lib/`: Data access layer (API implementations, repositories, data sources).
18+
- `/modules/common/lib/`: Shared code (constants, themes, helpers, extensions, mixins).
19+
20+
### Architectural Guidelines:
21+
- The project uses **Bloc/Cubit** for state management and dependency injection.
22+
- Each feature is modularized and follows a clean architecture pattern.
23+
- The UI layer is responsible for rendering the user interface and handling user interactions.
24+
- State management is handled using **Bloc/Cubit**.
25+
- The application uses a Service-based approach for domain logic organization.
26+
- Services (e.g., AuthService) are responsible for entire domain areas and coordinate between repositories and cubits.
27+
- Each functional area has its own Cubit with associated states located under `/modules/domain/lib/bloc/{feature}/`.
28+
- UI for each feature must live in `/app/lib/presentation/ui/pages/{feature}/{feature}_page.dart`.
29+
- Pages can be split into smaller widgets if needed, but keep all within the same feature folder.
30+
- Cubits should not directly communicate with one another. Instead, widgets observe cubits via BlocProvider/BlocBuilder and services coordinate complex operations.
31+
- Always adhere to naming conventions and clean architecture best practices.
32+
33+
### Agent instructions: |
34+
When given a Jira ticket or feature request:
35+
- First, analyze the provided information to understand the feature requirements.
36+
- Identify the necessary components and files needed to implement the feature.
37+
- Verify if the Jira ticket specified any Figma designs or UI specifications.
38+
- If the Jira ticket does not specify designs, use your expertise to create a clean, functional UI that aligns with the overall project design language.
39+
- If the Jira ticket specified the Figma design, connect to the Figma API to retrieve the design and generate the UI code accordingly.
40+
- Verify the current codebase for existing files that may be reused or extended.
41+
- If the feature requires new files, ensure they are created within the correct modular boundaries.
42+
- Generate all necessary Flutter code files required to implement the described feature.
43+
- For each file, output:
44+
- The **full file path**
45+
- The **complete Dart code**, fully functional and following best practices.
46+
- Mandatory files for each feature:
47+
- `/app/lib/presentation/ui/pages/{feature}/{feature}_page.dart`: UI and widgets.
48+
- `/modules/domain/lib/bloc/{feature}/{feature}_cubit.dart`: Cubit for state management.
49+
- `/modules/domain/lib/bloc/{feature}/{feature}_state.dart`: State classes for the Cubit.
50+
- `/modules/domain/lib/services/{Feature}_service.dart`: Service class if needed.
51+
- Additional files (e.g., models, repository interfaces or implementations) **only if required** by the feature and placed in:
52+
- `/modules/domain/lib/`
53+
- `/modules/data/lib/`
54+
- Never create files or code outside the specified modular boundaries.
55+
56+
- Add clear code comments throughout.
57+
- Insert `// TODO:` comments wherever information is missing, ambiguous, or requires clarification.
58+
- If Jira includes code-related comments or specific implementation notes, **honor and implement them**.
59+
- Use idiomatic Flutter and Bloc/Cubit patterns, clean architecture principles, and ensure code is maintainable and modular.
60+
61+
### output_format: |
62+
- For each file:
63+
- Print the full path (e.g., `/app/lib/presentation/ui/pages/login/login_page.dart`)

‎.cursor/rules/data_management.mdc‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: true
5+
---
6+
---
7+
description: Rules for data handling and entity parsing in the data module
8+
globs: ["modules/data/**/*.dart"]
9+
alwaysApply: true
10+
---
11+
12+
- This module is responsible exclusively for data handling and creation (Data Sources, DTOs, and Entities).
13+
- Entities created here should only handle JSON parsing.
14+
- Each `Entity` must have a corresponding model in the `domain` module.
15+
- Class names must end with `Entity`. Example: `NotificationEntity`.
16+
- The corresponding file must follow snake_case formatting: `notification_entity.dart`.
17+
- For fields like `price` that may come as `int`, `double`, or `String`, use the helper `parseFlexibleNumber(dynamic value)` to avoid type-related errors.

‎.cursor/rules/flutter_architecture.mdc‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
description:
3+
globs:
4+
alwaysApply: true
5+
---
6+
---
7+
description: Architectural rules for a Flutter project using Bloc Cubit
8+
globs: ["**/*.dart"]
9+
alwaysApply: true
10+
---
11+
12+
# Flutter Project Coding Standards
13+
14+
## Project Structure & Architecture
15+
16+
Follow a strict modular architecture:
17+
18+
- `/app/lib/`: Presentation layer (screens, widgets, routes).
19+
- `/modules/domain/lib/`: Core business logic (services, cubits, abstract repositories, models).
20+
- `/modules/data/lib/`: Data access (API clients, DTOs, data sources, and `Entity` classes).
21+
- `/modules/common/lib/`: Shared utilities, themes, constants, and mixins.
22+
23+
### Service & Cubit Communication
24+
25+
- Cubits **must not** communicate directly with one another.
26+
- Services coordinate between repositories and cubits for complex operations.
27+
- Widgets are responsible for observing their respective cubit's state via BlocProvider/BlocBuilder and triggering actions as needed.
28+
29+
---
30+
31+
## Naming Conventions
32+
33+
- **PascalCase** for class names, enums, and type aliases.
34+
- **camelCase** for variables, functions, and parameters.
35+
- Prefix **private members** with an underscore `_`.
36+
- Use **ALL_CAPS** for constants (e.g., `const MAX_ITEMS = 10;`).
37+
- **File names** must follow **snake_case** (e.g., `user_profile_cubit.dart`).
38+
- **Cubit files** must end with `_cubit.dart` and state files with `_state.dart`.
39+
- **Service files** must use PascalCase followed by `Service.dart` (e.g., `AuthService.dart`).
40+
- **Widget files** must end with `_page.dart` or `_widget.dart` depending on scope.
41+
42+
---
43+
44+
## Data Module Guidelines
45+
46+
The `/modules/data/lib/` folder is exclusively for data handling:
47+
48+
- Data sources (API, DB)
49+
- DTOs
50+
- `Entity` classes
51+
52+
### Entity Standards
53+
54+
- Each entity class must end with `Entity`, e.g., `UserEntity`.
55+
- File names for entities must be snake_case: `user_entity.dart`.
56+
- Entities must implement **JSON parsing logic only**.
57+
- For fields like `price` or `amount` that may come as `int`, `double`, or `String`, use:
58+
59+
```dart
60+
num parseFlexibleNumber(dynamic value) {
61+
if (value is num) return value;
62+
return num.tryParse(value.toString()) ?? 0;
63+
}
64+
```
65+
66+
### Mapping
67+
68+
- Each `Entity` must have a corresponding domain `Model` in `/modules/domain/lib/` used in business logic.
69+
70+
---
71+
72+
## Error Handling
73+
74+
- Use `try/catch` for all asynchronous operations.
75+
- Always log errors with contextual information using `debugPrint`, `log`, or your logging utility.
76+
- Avoid silently swallowing errors.
77+
- Prefer using custom error types (`AppException`, `NetworkException`, etc.) in repositories or use cases.
78+
79+
---
80+
81+
## State Management (Bloc/Cubit)
82+
83+
- Use **Bloc/Cubit** for state management across all features.
84+
- Each feature must have its own cubit under `/modules/domain/lib/bloc/{feature}/`.
85+
- Each cubit must have corresponding state classes in `/modules/domain/lib/bloc/{feature}/`.
86+
- Services coordinate between repositories and cubits, located under `/modules/domain/lib/services/`.
87+
- Avoid shared/global cubits unless absolutely necessary.
88+
- Cubits manage the complete screen state through state transitions.
89+
- Use `BlocProvider`, `BlocBuilder`, `BlocListener`, or `BlocConsumer` to react to state changes in widgets.
90+
91+
---
92+
93+
## TODOs and Comments
94+
95+
- Use `// TODO:` for areas where logic is incomplete or unclear.
96+
- Use `// FIXME:` for known bugs, temporary workarounds, or technical debt.
97+
98+
---

‎.github/instructions/copilot-agent.instructions.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
---
2+
applyTo: "app/lib/**/*.dart, modules/data/lib/**/*.dart, modules/domain/lib/**/*.dart, modules/common/lib/**/*.dart"
3+
---
4+
5+
## description: |
6+
You are a senior Flutter engineer working on a modular Flutter project. The codebase follows a layered architecture with the following directory structure:
7+
8+
- `/app/lib/`: Main application layer (presentation widgets, navigation, routing).
9+
- `/modules/domain/lib/`: Core business logic (entities, services, cubits, states).
10+
- `/modules/data/lib/`: Data access layer (API implementations, repositories, data sources).
11+
- `/modules/common/lib/`: Shared code (constants, themes, helpers, extensions, mixins).
12+
13+
### Architectural Guidelines:
14+
- The project uses **Bloc/Cubit** for state management and dependency injection.
15+
- Each feature is modularized and follows a clean architecture pattern.
16+
- The UI layer is responsible for rendering the user interface and handling user interactions.
17+
- State management is handled using **Bloc/Cubit**.
18+
- The application uses a Service-based approach for domain logic organization.
19+
- Services (e.g., AuthService) are responsible for entire domain areas and coordinate between repositories and cubits.
20+
- Each functional area has its own Cubit with associated states located under `/modules/domain/lib/bloc/{feature}/`.
21+
- UI for each feature must live in `/app/lib/presentation/ui/pages/{feature}/{feature}_page.dart`.
22+
- Pages can be split into smaller widgets if needed, but keep all within the same feature folder.
23+
- Cubits should not directly communicate with one another. Instead, widgets observe cubits via BlocProvider/BlocBuilder and services coordinate complex operations.
24+
- Always adhere to naming conventions and clean architecture best practices.
25+
26+
### Copilot instructions: |
27+
When given a Jira ticket or feature request:
28+
- First, analyze the provided information to understand the feature requirements.
29+
- Identify the necessary components and files needed to implement the feature.
30+
- Verify if the Jira ticket specified any Figma designs or UI specifications.
31+
- If the Jira ticket does not specify designs, use your expertise to create a clean, functional UI that aligns with the overall project design language.
32+
- If the Jira ticket specified the Figma design, connect to the Figma API to retrieve the design and generate the UI code accordingly.
33+
- Verify the current codebase for existing files that may be reused or extended.
34+
- If the feature requires new files, ensure they are created within the correct modular boundaries.
35+
- Generate all necessary Flutter code files required to implement the described feature.
36+
- For each file, output:
37+
- The **full file path**
38+
- The **complete Dart code**, fully functional and following best practices.
39+
- Mandatory files for each feature:
40+
- `/app/lib/presentation/ui/pages/{feature}/{feature}_page.dart`: UI and widgets.
41+
- `/modules/domain/lib/bloc/{feature}/{feature}_cubit.dart`: Cubit for state management.
42+
- `/modules/domain/lib/bloc/{feature}/{feature}_state.dart`: State classes for the Cubit.
43+
- `/modules/domain/lib/services/{Feature}_service.dart`: Service class if needed.
44+
- Additional files (e.g., models, repository interfaces or implementations) **only if required** by the feature and placed in:
45+
- `/modules/domain/lib/`
46+
- `/modules/data/lib/`
47+
- Never create files or code outside the specified modular boundaries.
48+
49+
- Add clear code comments throughout.
50+
- Insert `// TODO:` comments wherever information is missing, ambiguous, or requires clarification.
51+
- If Jira includes code-related comments or specific implementation notes, **honor and implement them**.
52+
- Use idiomatic Flutter and Bloc/Cubit patterns, clean architecture principles, and ensure code is maintainable and modular.
53+
54+
### output_format: |
55+
- For each file:
56+
- Print the full path (e.g., `/app/lib/presentation/ui/pages/login/login_page.dart`)

‎.github/instructions/flutter.instructions.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
applyTo: "app/lib/**/*.dart, modules/data/lib/**/*.dart, modules/domain/lib/**/*.dart, modules/common/lib/**/*.dart"
3+
---
4+
5+
# Flutter Project Coding Standards
6+
7+
## Project Structure & Architecture
8+
9+
Follow a strict modular architecture:
10+
11+
- `/app/lib/`: Presentation layer (screens, widgets, routes).
12+
- `/modules/domain/lib/`: Core business logic (services, cubits, abstract repositories, models).
13+
- `/modules/data/lib/`: Data access (API clients, DTOs, data sources, and `Entity` classes).
14+
- `/modules/common/lib/`: Shared utilities, themes, constants, and mixins.
15+
16+
### Service & Cubit Communication
17+
18+
- Cubits **must not** communicate directly with one another.
19+
- Services coordinate between repositories and cubits for complex operations.
20+
- Widgets are responsible for observing their respective cubit's state via BlocProvider/BlocBuilder and triggering actions as needed.
21+
22+
---
23+
24+
## Naming Conventions
25+
26+
- **PascalCase** for class names, enums, and type aliases.
27+
- **camelCase** for variables, functions, and parameters.
28+
- Prefix **private members** with an underscore `_`.
29+
- Use **ALL_CAPS** for constants (e.g., `const MAX_ITEMS = 10;`).
30+
- **File names** must follow **snake_case** (e.g., `user_profile_cubit.dart`).
31+
- **Cubit files** must end with `_cubit.dart` and state files with `_state.dart`.
32+
- **Service files** must use PascalCase followed by `Service.dart` (e.g., `AuthService.dart`).
33+
- **Widget files** must end with `_page.dart` or `_widget.dart` depending on scope.
34+
35+
---
36+
37+
## Data Module Guidelines
38+
39+
The `/modules/data/lib/` folder is exclusively for data handling:
40+
41+
- Data sources (API, DB)
42+
- DTOs
43+
- `Entity` classes
44+
45+
### Entity Standards
46+
47+
- Each entity class must end with `Entity`, e.g., `UserEntity`.
48+
- File names for entities must be snake_case: `user_entity.dart`.
49+
- Entities must implement **JSON parsing logic only**.
50+
- For fields like `price` or `amount` that may come as `int`, `double`, or `String`, use:
51+
52+
```dart
53+
num parseFlexibleNumber(dynamic value) {
54+
if (value is num) return value;
55+
return num.tryParse(value.toString()) ?? 0;
56+
}
57+
```
58+
59+
### Mapping
60+
61+
- Each `Entity` must have a corresponding domain `Model` in `/modules/domain/lib/` used in business logic.
62+
63+
---
64+
65+
## Error Handling
66+
67+
- Use `try/catch` for all asynchronous operations.
68+
- Always log errors with contextual information using `debugPrint`, `log`, or your logging utility.
69+
- Avoid silently swallowing errors.
70+
- Prefer using custom error types (`AppException`, `NetworkException`, etc.) in repositories or use cases.
71+
72+
---
73+
74+
## State Management (Bloc/Cubit)
75+
76+
- Use **Bloc/Cubit** for state management across all features.
77+
- Each feature must have its own cubit under `/modules/domain/lib/bloc/{feature}/`.
78+
- Each cubit must have corresponding state classes in `/modules/domain/lib/bloc/{feature}/`.
79+
- Services coordinate between repositories and cubits, located under `/modules/domain/lib/services/`.
80+
- Avoid shared/global cubits unless absolutely necessary.
81+
- Cubits manage the complete screen state through state transitions.
82+
- Use `BlocProvider`, `BlocBuilder`, `BlocListener`, or `BlocConsumer` to react to state changes in widgets.
83+
84+
---
85+
86+
## TODOs and Comments
87+
88+
- Use `// TODO:` for areas where logic is incomplete or unclear.
89+
- Use `// FIXME:` for known bugs, temporary workarounds, or technical debt.
90+
91+
---

‎app/lib/main/env/env_config.dart‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,30 @@
1-
import 'package:domain/env/env_config.dart';
1+
import 'package:flutter_dotenv/flutter_dotenv.dart';
22

3-
enum Flavor { dev, qa, prod }
3+
enum Flavor {
4+
dev,
5+
qa,
6+
prod;
7+
8+
static Flavor fromString(String value) {
9+
return Flavor.values.firstWhere(
10+
(flavor) => flavor.name == value,
11+
orElse: () => Flavor.dev,
12+
);
13+
}
14+
}
15+
16+
class Environment {
17+
static String get clientSecret => dotenv.env['SECRET_KEY'] ?? '';
18+
19+
static String? get portalUrl => dotenv.env['API_URL'];
20+
21+
static String get envName => const String.fromEnvironment(
22+
'ENV',
23+
defaultValue: 'dev',
24+
);
25+
26+
static String get envConfigFile => 'env/.$envName';
27+
}
428

529
class FlavorValues {
630

‎app/lib/main/init.dart‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import 'package:app/main/app.dart';
2+
import 'package:app/main/env/env_config.dart';
23
import 'package:common/init.dart';
34
import 'package:data/init.dart';
45
import 'package:domain/init.dart';
@@ -21,7 +22,8 @@ void init() async {
2122
final getIt = GetIt.instance;
2223

2324
Future<void> initialize() async {
24-
await dotenv.load(fileName: FlavorConfig.getEnvFilePath());
25+
await dotenv.load(fileName: Environment.envConfigFile);
26+
2527
await CommonInit.initialize(getIt);
2628
await DataInit.initialize(getIt);
2729
await DomainInit.initialize(getIt);

‎app/pubspec.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,7 @@ dependencies:
6060
http: ^1.5.0
6161
melos: ^3.4.0
6262
dev: ^1.0.0
63+
flutter_dotenv: ^5.2.1
6364

6465
dev_dependencies:
6566
bloc_test: ^9.0.2

0 commit comments

Comments
 (0)