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

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)

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 - Understand the high-level design
• State Management - Learn the Provider patterns
• Contributing Guide - Guide to extending the app