> ## Documentation Index > Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Project Structure > Comprehensive guide to the Invenicum project directory organization ## Overview The Invenicum project follows Flutter conventions with a well-organized structure that separates concerns and promotes maintainability. ## Root Directory Structure ``` source/ ├── lib/ # Main application code ├── assets/ # Static resources (images, fonts) ├── pubspec.yaml # Dependencies and configuration ├── analysis_options.yaml # Linting rules └── test/ # Unit and widget tests ``` ## lib/ Directory Breakdown ### High-Level Organization ``` lib/ ├── main.dart # Application entry point ├── config/ # Configuration files ├── core/ # Core utilities and infrastructure ├── data/ # Data layer (services, models) ├── providers/ # State management ├── screens/ # UI screens ├── widgets/ # Reusable widgets └── l10n/ # Localization files ``` ## Detailed Structure ### 1. Entry Point **`lib/main.dart`** The application bootstraps here: * Provider hierarchy setup (`lib/main.dart:64-261`) * Router configuration * Theme initialization * Localization configuration ```dart theme={null} void main() async { WidgetsFlutterBinding.ensureInitialized(); final authProvider = AuthProvider(); runApp( MultiProvider( providers: [ // Services (singletons) // State providers ], child: const MyApp(), ), ); } ``` ### 2. Configuration Layer **`lib/config/`** Centralized configuration management: ``` config/ └── environment.dart # API URLs, timeouts, keys ``` **Purpose**: Single source of truth for environment variables, avoiding hardcoded values throughout the app. ### 3. Core Infrastructure **`lib/core/`** Core utilities shared across the application: ``` core/ ├── routing/ │ └── app_router.dart # GoRouter configuration └── utils/ └── sdk_plugin_parser.dart # STAC action parser for plugins ``` **Key files**: * **`app_router.dart`**: Defines all routes, auth guards, deep-link handling * **`sdk_plugin_parser.dart`**: Custom action parser for the plugin system ### 4. Data Layer **`lib/data/`** Contains all data-related code: ``` data/ ├── models/ # Data models └── services/ # API services ``` #### Models (`lib/data/models/`) Data Transfer Objects (DTOs) representing API responses and business entities: ``` models/ ├── user_data_model.dart # User profile ├── login_response.dart # Authentication response ├── inventory_item.dart # Asset/item model ├── inventory_item_response.dart # Paginated response wrapper ├── container_node.dart # Container hierarchy ├── asset_type_model.dart # Asset type definition ├── custom_field_definition_model.dart # Dynamic field schemas ├── location.dart # Location/sublocation ├── loan.dart # Loan/lending records ├── alert.dart # Notification/alert ├── dashboard_stats.dart # Dashboard metrics ├── store_plugin_model.dart # Plugin metadata ├── asset_template_model.dart # Reusable templates ├── achievements_model.dart # Gamification ├── user_preferences.dart # User settings ├── user_theme_config_model.dart # Theme customization ├── price_history_point.dart # Market value tracking └── veni_response.dart # AI chatbot responses ``` **Pattern**: All models implement `fromJson()` and `toJson()` for serialization. #### Services (`lib/data/services/`) API integration layer: ``` services/ ├── api_service.dart # Base HTTP client (Dio) ├── inventory_item_service.dart # Items/assets CRUD ├── container_service.dart # Containers management ├── asset_type_service.dart # Asset type operations ├── location_service.dart # Locations CRUD ├── loan_service.dart # Lending operations ├── alert_service.dart # Notifications ├── dashboard_service.dart # Dashboard data ├── plugin_service.dart # Plugin marketplace ├── template_service.dart # Template management ├── integrations_service.dart # Third-party integrations ├── preferences_service.dart # User preferences ├── theme_service.dart # Theme persistence ├── achievements_service.dart # Achievements/gamification ├── voucher_service.dart # Delivery vouchers ├── report_service.dart # Report generation ├── asset_print_service.dart # Label printing ├── toast_service.dart # Toast notifications (UI helper) ├── veni_chatbot_service.dart # AI chatbot integration └── ai_service.dart # AI/ML features ``` **Service Pattern**: * All services receive `ApiService` via constructor * Use `dio` from `ApiService` for HTTP calls * Transform JSON to models using `Model.fromJson()` * Throw exceptions for error handling **Example**: ```dart theme={null} class InventoryItemService { final ApiService _api; InventoryItemService(this._api); Future getItem(int id) async { final response = await _api.dio.get('/items/$id'); return InventoryItem.fromJson(response.data); } } ``` ### 5. State Management Layer **`lib/providers/`** All application state is managed through ChangeNotifier providers: ``` providers/ ├── auth_provider.dart # Authentication state ├── inventory_item_provider.dart # Inventory items state ├── container_provider.dart # Container hierarchy state ├── location_provider.dart # Locations state ├── loan_provider.dart # Loans state ├── alert_provider.dart # Alerts/notifications state ├── dashboard_provider.dart # Dashboard data ├── plugin_provider.dart # Plugin management ├── template_provider.dart # Templates state ├── integrations_provider.dart # Integration status ├── preferences_provider.dart # User preferences ├── theme_provider.dart # Theme customization └── achievement_provider.dart # Achievements state ``` **Provider Responsibilities**: * Manage domain-specific state (loading, data, errors) * Call services for data operations * Implement caching strategies * Notify listeners on state changes * Handle filtering, sorting, pagination (client-side) **See [State Management](https://lopiv2-invenicum-25.mintlify.site/development/state-management.md) for detailed patterns.** ### 6. Presentation Layer **`lib/screens/`** Full-page screens organized by feature: ``` screens/ ├── home/ │ ├── login_screen.dart │ ├── dashboard_screen.dart │ ├── profile_screen.dart │ └── local_widgets/ # Screen-specific widgets │ ├── chatbot_veni_widget.dart │ ├── search_bar_widget.dart │ ├── total_market_value_widget.dart │ └── ... ├── assets/ │ ├── asset_list_screen.dart │ ├── asset_detail_screen.dart │ ├── asset_create_screen.dart │ ├── asset_edit_screen.dart │ ├── asset_import_screen.dart │ └── local_widgets/ │ ├── asset_grid_view.dart │ ├── asset_search_bar.dart │ └── ... ├── asset_types/ │ ├── asset_type_grid_screen.dart │ ├── asset_type_create_screen.dart │ ├── asset_type_edit_screen.dart │ └── local_widgets/ ├── locations/ │ ├── locations_screen.dart │ ├── location_create_screen.dart │ ├── location_edit_screen.dart │ └── local_widgets/ ├── loans/ │ ├── loans_screen.dart │ ├── loan_create_screen.dart │ └── local_widgets/ ├── alerts/ │ └── alerts_screen.dart ├── preferences/ │ ├── preferences_screen.dart │ ├── delivery_voucher_editor_screen.dart │ └── local_widgets/ ├── reports/ │ └── reports_screen.dart ├── templates/ │ ├── asset_templates_market_screen.dart │ ├── asset_template_detail_screen.dart │ ├── asset_template_editor_screen.dart │ └── local_widgets/ ├── plugins/ │ ├── plugins_screen.dart │ └── local_widgets/ ├── integrations/ │ ├── integrations_screen.dart │ └── local_widgets/ ├── achievements/ │ └── achievements_screen.dart └── datalists/ ├── datalist_grid_screen.dart ├── datalist_create_screen.dart └── datalist_edit_screen.dart ``` **Screen Organization Pattern**: * Each feature has its own directory * Main screens at the top level * `local_widgets/` for screen-specific components (not reusable) * CRUD pattern: List, Detail, Create, Edit screens ### 7. Reusable Widgets **`lib/widgets/`** Shared widgets used across multiple screens: ``` widgets/ ├── layout/ │ ├── main_layout.dart # App shell (header, sidebar, content) │ └── sidebar_layout.dart # Navigation sidebar └── ui/ ├── stac_slot.dart # Plugin injection point └── [other reusable components] ``` **Key widgets**: * **`main_layout.dart`**: Wraps all authenticated routes, provides header, sidebar, and plugin slots * **`sidebar_layout.dart`**: Hierarchical navigation (containers, asset types, locations) * **`stac_slot.dart`**: Dynamic widget slot for plugin UI injection ### 8. Localization **`lib/l10n/`** Internationalization files: ``` l10n/ ├── app_en.arb # English translations ├── app_es.arb # Spanish translations └── app_localizations.dart # Generated localization class ``` **Usage**: ```dart theme={null} final l10n = AppLocalizations.of(context); Text(l10n.welcome); ``` **Configuration**: `pubspec.yaml:89` enables `generate: true` for l10n. ## Assets Organization **`assets/`** ``` assets/ └── images/ └── invenicum_logo.png ``` **Declared in**: `pubspec.yaml:92-93` ## Dependencies **`pubspec.yaml`** Key dependencies: ```yaml theme={null} dependencies: # Core flutter_sdk # Navigation go_router: ^17.0.1 # State Management provider: ^6.1.5+1 # Networking dio: ^5.9.0 # Storage flutter_secure_storage: ^10.0.0 shared_preferences: ^2.5.4 # UI Components data_table_2: ^2.6.0 cached_network_image: ^3.4.1 fl_chart: ^1.1.1 carousel_slider: ^5.1.2 # Utilities intl: any collection: ^1.19.1 csv: ^6.0.0 # Plugin System stac: ^1.3.1 # Notifications fluttertoast: ^9.0.0 toastification: ^3.0.3 # Other qr_flutter: ^4.1.0 pdf: ^3.11.3 printing: ^5.14.2 ``` ## File Naming Conventions 1. **Dart files**: `snake_case.dart` * Example: `inventory_item_provider.dart` 2. **Screens**: `{feature}_{action}_screen.dart` * Example: `asset_create_screen.dart` 3. **Widgets**: `{name}_widget.dart` * Example: `search_bar_widget.dart` 4. **Models**: `{entity}_model.dart` or `{entity}.dart` * Example: `user_data_model.dart`, `loan.dart` 5. **Services**: `{domain}_service.dart` * Example: `inventory_item_service.dart` 6. **Providers**: `{domain}_provider.dart` * Example: `auth_provider.dart` ## Code Organization Best Practices ### Import Ordering Follow this order in import statements: ```dart theme={null} // 1. Dart SDK import 'dart:convert'; // 2. Flutter SDK import 'package:flutter/material.dart'; // 3. Third-party packages import 'package:provider/provider.dart'; import 'package:go_router/go_router.dart'; // 4. Local imports (relative) import '../models/user.dart'; import '../services/api_service.dart'; ``` ### Directory Depth * Keep nesting to **maximum 3 levels** when possible * Use `local_widgets/` to avoid cluttering screen directories * Group related screens in feature directories ### Module Boundaries * **Screens** should NOT import from other screen directories * **Widgets** should be truly reusable (no business logic) * **Providers** should NOT import screens or widgets * **Services** should be pure (no Flutter dependencies except `debugPrint`) ## Navigation Patterns ### Route Paths Routes follow REST-like patterns: ``` /dashboard /container/:containerId/asset-types /container/:containerId/asset-types/:assetTypeId/assets /container/:containerId/asset-types/:assetTypeId/assets/:assetId /container/:containerId/asset-types/:assetTypeId/assets/:assetId/edit ``` **Defined in**: `lib/core/routing/app_router.dart` ## Next Steps * [Architecture Overview](https://lopiv2-invenicum-25.mintlify.site/development/architecture.md) - Understand the high-level design * [State Management](https://lopiv2-invenicum-25.mintlify.site/development/state-management.md) - Learn the Provider patterns * [Contributing Guide](https://lopiv2-invenicum-25.mintlify.site/development/contributing.md) - Guide to extending the app This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.