Skip to main content

​
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
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: 
class InventoryItemService {
  final ApiService _api;
  
  InventoryItemService(this._api);
  
  Future<InventoryItem> 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 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: 
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: 
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: 
// 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)

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us