ntc-dev-kit 1.0.0__py3-none-any.whl

ntc/templates/flutter/.knowledge/knowledge_description.md

@@ -0,0 +1,215 @@
+# Architecture Overview - {project_name}
+
+This document provides a comprehensive overview of the architecture and technical stack for this NTC-generated Flutter project.
+
+## 🏗️ Architecture Overview
+
+This is a modern Flutter mobile application built with Dart, Riverpod state management, and a clean architecture pattern designed for cross-platform development.
+
+### Core Architecture Principles
+
+- **Feature-Based Architecture**: Organized by features for better maintainability
+- **Clean Architecture**: Separation of concerns with layers (presentation, domain, data)
+- **Type Safety**: Dart 3 with null safety for compile-time type checking
+- **State Management**: Riverpod for reactive state management
+- **Dependency Injection**: Riverpod providers for dependency injection
+
+## 🛠️ Technical Stack
+
+### Flutter Framework
+- **Flutter 3.19+**: Latest Flutter SDK
+- **Dart 3.9+**: Latest Dart language with null safety
+- **Platform Support**: Android, iOS, Web, Windows, macOS, Linux
+
+### State Management
+- **Riverpod 2.4+**: Reactive state management
+- **StateNotifier**: For complex stateful logic
+- **ProviderScope**: Root provider scope
+
+### Networking & HTTP
+- **Dio 5.4+**: Powerful HTTP client
+- **Connectivity Plus**: Network connectivity monitoring
+- **Flutter Secure Storage**: Secure token storage
+
+### Local Storage
+- **Hive 2.2+**: Fast local key-value database
+- **Hive Flutter**: Hive integration for Flutter
+- **Shared Preferences**: Simple key-value storage
+
+### Internationalization
+- **Flutter Localizations**: Built-in localization support
+- **Intl**: Internationalization utilities
+
+### UI & Theming
+- **Google Fonts**: Custom font integration
+- **Cached Network Image**: Image caching
+- **Material Design 3**: Latest Material Design components
+
+### Development Tools
+- **Flutter Lints**: Code linting and style enforcement
+- **Analysis Options**: Custom linting configuration
+
+## 📊 Data Flow Architecture
+
+### API Communication Flow
+```
+Widget → Riverpod Provider → ApiService → DioClient → Backend API
+                                    ↓
+                            Interceptors
+                                    ↓
+                        Auth Token Injection
+                                    ↓
+                        Error Handling
+```
+
+### State Management Flow
+```
+Widget → ConsumerWidget → Provider → StateNotifier → State Update → Widget Rebuild
+```
+
+## 🔐 Authentication Architecture
+
+### JWT Token Management
+- Tokens stored in Flutter Secure Storage
+- Automatic token injection via Dio interceptors
+- Token removal on 401 responses
+- Login/logout through API service
+
+### Secure Storage
+- Flutter Secure Storage for sensitive data
+- Hive for local data storage
+- Shared Preferences for simple settings
+
+## 🌐 API Service Architecture
+
+### Dio Client Configuration
+- Base URL from environment variable
+- 30-second timeout
+- JSON content-type headers
+- Request/response interceptors
+- Error handling utilities
+
+### Available Methods
+- `get(path, queryParameters)`: GET requests
+- `post(path, data, queryParameters)`: POST requests
+- `put(path, data, queryParameters)`: PUT requests
+- `patch(path, data, queryParameters)`: PATCH requests
+- `delete(path, queryParameters)`: DELETE requests
+
+## 📁 Widget Architecture
+
+### Widget Hierarchy
+```
+ProviderScope (Root)
+├── MaterialApp
+│   ├── Theme (MaterialApp)
+│   ├── Locale (MaterialApp)
+│   └── HomeScreen
+│       └── [Child Widgets]
+```
+
+### Widget Patterns
+- **ConsumerWidget**: For widgets that need providers
+- **ConsumerStatefulWidget**: For complex stateful widgets
+- **Const Widgets**: For static widgets
+- **StatelessWidget**: For simple stateless widgets
+
+## 🔧 Configuration Architecture
+
+### Environment Variables
+- `API_BASE_URL`: Backend API base URL
+- `ENV`: Environment (development/staging/production)
+- `SENTRY_DSN`: Sentry DSN for error tracking
+
+### Build Configuration
+- **Pubspec.yaml**: Dependencies and Flutter configuration
+- **Analysis Options.yaml**: Linting configuration
+- **Environment**: Build-time environment variables
+
+## 🚀 Build Process
+
+### Development Build
+- Flutter dev server with hot reload
+- Dart compilation on-the-fly
+- Source maps for debugging
+- Platform-specific debugging
+
+### Production Build
+- Dart compilation to native code
+- Code splitting and tree shaking
+- Asset optimization
+- Platform-specific build outputs:
+  - Android: APK/AAB
+  - iOS: IPA
+  - Web: HTML/JS/CSS
+  - Desktop: Native executables
+
+## 🎯 Performance Considerations
+
+### Optimization Strategies
+- Use const widgets where possible
+- Avoid unnecessary rebuilds with Riverpod
+- Use ListView.builder for long lists
+- Optimize images with CachedNetworkImage
+- Implement proper caching strategies
+
+### Best Practices
+- Use ConsumerWidget only when needed
+- Keep widgets small and focused
+- Extract reusable widgets
+- Use proper keys for lists
+- Implement lazy loading
+
+## 🔒 Security Considerations
+
+### Security Measures
+- HTTPS in production
+- Secure storage for tokens
+- Input validation
+- XSS prevention
+- CSRF protection (via backend)
+- Environment variable security
+
+### Environment Variable Security
+- Never commit secrets
+- Use build-time environment variables
+- Server-side secrets should not be exposed
+
+## 📈 Localization Architecture
+
+### Localization Features
+- AppLocalizations for string translations
+- Support for multiple languages (English, Swahili)
+- Locale persistence
+- Language switching
+
+### Best Practices
+- Use AppLocalizations for all user-facing strings
+- Support RTL languages if needed
+- Test all language variants
+- Use proper number/date formatting
+
+## 🔒 Accessibility Architecture
+
+### Accessibility Features
+- Semantic labels
+- Screen reader support
+- Proper touch targets
+- Color contrast compliance
+- Focus management
+
+## 📈 Scalability Architecture
+
+### Scalability Features
+- Feature-based organization
+- Service layer abstraction
+- Modular file structure
+- Easy integration with new features
+- Support for multiple API endpoints
+
+### Future Extensibility
+- Easy addition of new features
+- Integration with Firebase
+- Analytics integration
+- Push notifications
+- Background services

ntc/templates/flutter/.knowledge/knowledge_design_pattern.md

@@ -0,0 +1,310 @@
+# Design Patterns and Coding Conventions - {project_name}
+
+This document describes the design patterns and coding conventions used in this NTC-generated Flutter project.
+
+## 🎨 Widget Design Patterns
+
+### Stateless Widget Pattern
+```dart
+class MyWidget extends StatelessWidget {
+  const MyWidget({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return Container();
+  }
+}
+```
+
+### Consumer Widget Pattern (Riverpod)
+```dart
+class MyWidget extends ConsumerWidget {
+  const MyWidget({super.key});
+
+  @override
+  Widget build(BuildContext context, WidgetRef ref) {
+    final value = ref.watch(myProvider);
+    return Container();
+  }
+}
+```
+
+### Consumer Stateful Widget Pattern
+```dart
+class MyWidget extends ConsumerStatefulWidget {
+  const MyWidget({super.key});
+
+  @override
+  ConsumerState<MyWidget> createState() => _MyWidgetState();
+}
+
+class _MyWidgetState extends ConsumerState<MyWidget> {
+  @override
+  Widget build(BuildContext context) {
+    return Container();
+  }
+}
+```
+
+## 🔧 Service Layer Pattern
+
+### API Service Pattern
+```dart
+class ApiService {
+  static ApiService? _instance;
+  late DioClient _dioClient;
+
+  ApiService._() {
+    _dioClient = DioClient.instance;
+  }
+
+  static ApiService get instance {
+    _instance ??= ApiService._();
+    return _instance!;
+  }
+
+  Future<Response> get(String path) async {
+    return _dioClient.dio.get(path);
+  }
+}
+```
+
+## 📝 Dart Patterns
+
+### Type Safety Pattern
+```dart
+// Always use specific types
+String name = 'John';
+int age = 30;
+List<String> items = ['a', 'b'];
+Map<String, int> map = {'key': 1};
+
+// Avoid dynamic
+// dynamic value = getValue(); // Avoid
+// String value = getValue(); // Prefer
+```
+
+### Null Safety Pattern
+```dart
+// Use nullable types when needed
+String? name;
+
+// Use null-aware operators
+name?.toUpperCase();
+name ?? 'Default';
+
+// Use late for late initialization
+late final ApiService _apiService;
+```
+
+### Async Pattern
+```dart
+Future<void> fetchData() async {
+  try {
+    final response = await apiService.get('/endpoint');
+    // Handle response
+  } catch (e) {
+    // Handle error
+  }
+}
+```
+
+## 🎯 State Management Patterns
+
+### Provider Pattern
+```dart
+final myProvider = Provider<int>((ref) {
+  return 42;
+});
+```
+
+### StateNotifier Pattern
+```dart
+class MyNotifier extends StateNotifier<int> {
+  MyNotifier() : super(0);
+
+  void increment() {
+    state++;
+  }
+}
+
+final myNotifierProvider = StateNotifierProvider<MyNotifier, int>((ref) {
+  return MyNotifier();
+});
+```
+
+### Family Provider Pattern
+```dart
+final myFamilyProvider = Provider.family<int, String>((ref, id) {
+  return int.parse(id);
+});
+```
+
+## 🔄 Async Pattern
+
+### Async Widget Pattern
+```dart
+class AsyncWidget extends ConsumerFutureWidget<String> {
+  const AsyncWidget({super.key});
+
+  @override
+  Future<String> build(BuildContext context, WidgetRef ref) async {
+    return await fetchData();
+  }
+
+  @override
+  Widget buildData(BuildContext context, WidgetRef ref, String data) {
+    return Text(data);
+  }
+
+  @override
+  Widget buildError(BuildContext context, WidgetRef ref, Object error, StackTrace? stackTrace) {
+    return Text('Error: $error');
+  }
+
+  @override
+  Widget buildLoading(BuildContext context, WidgetRef ref) {
+    return const CircularProgressIndicator();
+  }
+}
+```
+
+## 🎨 Layout Pattern
+
+### Scaffold Pattern
+```dart
+Scaffold(
+  appBar: AppBar(
+    title: const Text('Title'),
+  ),
+  body: const Center(
+    child: Text('Content'),
+  ),
+  floatingActionButton: FloatingActionButton(
+    onPressed: () {},
+    child: const Icon(Icons.add),
+  ),
+)
+```
+
+## 🎨 Styling Pattern
+
+### Theme Pattern
+```dart
+final theme = Theme.of(context);
+final colorScheme = theme.colorScheme;
+final textTheme = theme.textTheme;
+
+Text(
+  'Hello',
+  style: textTheme.titleLarge,
+)
+```
+
+## 📦 File Organization Patterns
+
+### Feature-Based Structure
+```
+lib/features/
+├── feature_name/
+│   ├── data/          # Data models and repositories
+│   ├── domain/        # Business logic
+│   └── presentation/  # UI components
+```
+
+### Type-Based Structure
+```
+lib/
+├── core/              # Core functionality
+├── features/          # Feature modules
+├── services/          # External services
+├── shared/            # Shared components
+├── types/             # Type definitions
+└── l10n/              # Localization
+```
+
+## 🔒 Error Handling Patterns
+
+### Try-Catch Pattern
+```dart
+Future<void> safeAsyncOperation() async {
+  try {
+    final result = await apiService.get('/endpoint');
+    return result;
+  } catch (error) {
+    debugPrint('Operation failed: $error');
+    rethrow;
+  }
+}
+```
+
+## 🚀 Performance Patterns
+
+### Const Pattern
+```dart
+// Use const for static widgets
+const Text('Hello');
+const Icon(Icons.add);
+
+// Use const constructors
+const MyWidget();
+```
+
+### ListView Builder Pattern
+```dart
+ListView.builder(
+  itemCount: items.length,
+  itemBuilder: (context, index) {
+    return ListTile(title: Text(items[index]));
+  },
+)
+```
+
+## 📐 Naming Conventions
+
+### Widgets
+- **File**: `snake_case.dart` (e.g., `user_profile.dart`)
+- **Widget**: `PascalCase` (e.g., `UserProfile`)
+
+### Providers
+- **File**: `snake_case_provider.dart` (e.g., `user_provider.dart`)
+- **Provider**: `camelCaseProvider` (e.g., `userProvider`)
+
+### Services
+- **File**: `snake_case_service.dart` (e.g., `api_service.dart`)
+- **Service**: `PascalCase` (e.g., `ApiService`)
+
+### Variables
+- **Local**: `camelCase` (e.g., `userName`)
+- **Private**: `_camelCase` (e.g., `_userName`)
+- **Constants**: `UPPER_SNAKE_CASE` (e.g., `API_BASE_URL`)
+
+## 🎯 Best Practices
+
+### Code Organization
+1. Keep widgets small and focused
+2. Extract reusable logic into providers
+3. Use const constructors where possible
+4. Organize imports (external, internal)
+5. Use relative imports for internal files
+
+### Performance
+1. Use const widgets where possible
+2. Avoid unnecessary rebuilds with Riverpod
+3. Use ListView.builder for long lists
+4. Optimize images with CachedNetworkImage
+5. Implement proper caching
+
+### Accessibility
+1. Use semantic labels
+2. Provide semantic labels for buttons
+3. Ensure proper contrast
+4. Test with screen readers
+5. Use proper touch targets
+
+### Security
+1. Sanitize user input
+2. Use HTTPS in production
+3. Validate data on client and server
+4. Never expose sensitive data
+5. Use environment variables for secrets

ntc/templates/flutter/.knowledge/knowledge_structure.md

@@ -0,0 +1,83 @@
+# Project Structure - {project_name}
+
+This document describes the complete project structure and organization for AI assistants to understand how to work with this codebase.
+
+## 📁 Root Directory Structure
+
+```
+{project_name}/
+├── .gitignore            # Git ignore patterns
+├── .knowledge/           # AI documentation (this directory)
+├── pubspec.yaml          # Flutter dependencies
+├── analysis_options.yaml # Dart linting configuration
+├── README.md             # Project documentation
+└── lib/                  # Source code
+```
+
+## 🏗️ Source Directory Structure (`lib/`)
+
+```
+lib/
+├── core/                  # Core functionality
+│   ├── config/           # Configuration files
+│   │   ├── app_config.dart      # App configuration
+│   │   └── environment.dart    # Environment configuration
+│   ├── constants/       # Application constants
+│   │   └── app_constants.dart  # App-wide constants
+│   ├── network/         # Networking layer
+│   │   └── dio_client.dart     # Dio HTTP client
+│   └── utils/           # Utility functions
+├── features/             # Feature-based organization
+│   └── home/            # Home feature
+│       └── presentation/
+│           └── home_screen.dart  # Home screen widget
+├── services/            # External services
+│   └── api_service.dart         # API service
+├── shared/              # Shared components
+│   ├── theme/           # Theme configuration
+│   │   ├── app_theme.dart      # App theme
+│   │   └── theme_provider.dart # Theme provider
+│   └── localization/    # Localization
+│       └── locale_provider.dart # Locale provider
+├── types/               # Type definitions
+├── l10n/                # Localization files
+│   └── app_localizations.dart # App localizations
+└── main.dart            # App entry point
+```
+
+## 🎯 Key Conventions
+
+### File Naming
+- **Dart files**: `snake_case.dart` (e.g., `user_profile.dart`)
+- **Widgets**: `PascalCase` (e.g., `UserProfile`)
+- **Providers**: `snake_case_provider.dart` (e.g., `user_provider.dart`)
+- **Services**: `snake_case_service.dart` (e.g., `api_service.dart`)
+
+### Import Patterns
+- **Relative imports**: Use relative imports for files within the same package
+- **Package imports**: Use package imports for external dependencies
+- **Core imports**: `import '../core/config/app_config.dart'`
+- **Feature imports**: `import '../features/home/presentation/home_screen.dart'`
+
+### Dart Patterns
+- **Type safety**: Always use specific types, avoid `dynamic`
+- **Null safety**: Use Dart 3 null safety features
+- **Const constructors**: Use `const` where possible for performance
+- **Async/await**: Use async/await for asynchronous operations
+
+## 🔄 Development Workflow
+
+1. **Install dependencies**: `flutter pub get`
+2. **Run development**: `flutter run`
+3. **Build for production**: `flutter build apk` or `flutter build ios`
+4. **Run tests**: `flutter test`
+5. **Run linter**: `flutter analyze`
+
+## 📋 Important Notes for AI
+
+- **Always use Dart 3+**: This project uses Dart 3 with null safety
+- **Follow the feature structure**: New features go in `lib/features/`
+- **Use Riverpod**: State management is done with Riverpod
+- **Handle errors**: Always handle errors gracefully with user feedback
+- **Use environment variables**: Configuration via `String.fromEnvironment()`
+- **Platform support**: This template supports Android, iOS, Web, Windows, macOS, Linux