Skip to main content

📱 SIMANTRA - MOBILE

Project Name: Simantra Remastered 2023
Platform: Flutter (Multi-platform: Android & iOS)
Language: Dart
Version: 1.0.0
Min SDK Android: 21
Dart SDK: >= 2.18.5 < 3.0.0

📋 Daftar Isi​

  1. Gambaran Umum Project
  2. Struktur Folder Project
  3. Dependencies & Packages
  4. Arsitektur Project
  5. Setup & Environment
  6. Cara Menjalankan Project
  7. Fitur Utama
  8. Database & Storage
  9. Authentication & Security
  10. API Integration
  11. State Management
  12. Tips untuk Developer Selanjutnya
  13. Build & Release
  14. Troubleshooting

🎯 Gambaran Umum Project​

Simantra adalah aplikasi mobile untuk PT. Kalbe Nutritionals yang dirancang untuk mengelola proses:

  • Loading - Proses pengambilan barang
  • Unloading - Proses pengeluaran barang
  • Security Check - Pemeriksaan keamanan
  • QR Code Scanning - Verifikasi produk dengan barcode scanner

Aplikasi ini mendukung berbagai peran pengguna:

  • SECURITY
  • CHECKER
  • VERIFICATOR

📁 Struktur Folder Project​

simantra-flutter/
│
├── android/                      # Konfigurasi native Android
│   ├── app/                     # Main Android app
│   ├── gradle/                  # Gradle wrapper & konfigurasi build
│   ├── build.gradle             # Build configuration
│   ├── settings.gradle
│   ├── local.properties
│   └── gradlew / gradlew.bat    # Gradle build tools
│
├── ios/                          # Konfigurasi native iOS
│   ├── Runner/                  # Main iOS app
│   ├── Podfile                  # CocoaPods dependencies
│   └── Runner.xcworkspace/
│
├── lib/                          # Main Flutter application code
│   ├── main.dart               # Entry point aplikasi
│   │
│   ├── blocs/                   # BLoC State Management
│   │   ├── auth/               # Authentication logic
│   │   ├── loading/            # Loading process BLoC
│   │   ├── scanner/            # Barcode scanner BLoC
│   │   ├── security_checker/   # Security check BLoC
│   │   ├── token/              # Token management
│   │   ├── unloading/          # Unloading process BLoC
│   │   └── user_info/          # User information BLoC
│   │
│   ├── core/                    # Core utilities & constants
│   │   ├── constants.dart      # Global constants
│   │   ├── basic_state.dart    # Base state class
│   │   ├── failure.dart        # Error/Failure handling
│   │   ├── util_funct.dart     # Utility functions
│   │   ├── my_text.dart        # Custom text widgets
│   │   ├── img.dart            # Image utilities
│   │   ├── r.dart              # Resource generator
│   │   ├── InitHiveAdapter.dart # Hive database setup
│   │   └── R/                  # Generated resources
│   │
│   ├── model/                   # Data models & entities
│   │   ├── auth/               # Authentication models
│   │   ├── loader/             # Loading/Unloading models
│   │   └── ...                 # Other domain models
│   │
│   ├── network/                 # API & Network layer
│   │   ├── dio_client.dart     # Dio HTTP client
│   │   ├── interceptors/       # Request/Response interceptors
│   │   └── api_endpoints.dart  # API endpoints definition
│   │
│   ├── network_model/           # API request/response models
│   │   ├── requests/
│   │   └── responses/
│   │
│   ├── repositories/            # Repository pattern implementation
│   │   ├── login_repositories.dart
│   │   ├── loading_repositories.dart
│   │   ├── unloading_repositories.dart
│   │   ├── checker_repositories.dart
│   │   ├── security_repositories.dart
│   │   └── token_repositories.dart
│   │
│   └── ui/                      # User Interface layer
│       ├── pages/              # Page/Screen widgets
│       │   ├── login/          # Login & splash screen
│       │   ├── home/           # Home page
│       │   ├── checker/        # Checker pages
│       │   ├── security_checker/ # Security checker pages
│       │   ├── verificator/    # Verificator pages
│       │   └── ...
│       └── widget/             # Reusable UI components
│           └── qr_scanner_page.dart
│
├── assets/                      # Static assets
│   ├── images/                 # PNG, JPEG images
│   └── fonts/                  # Custom fonts (KalbeHelix)
│
├── test/                        # Unit & Widget tests
│   └── widget_test.dart
│
├── build/                       # Generated build files (git ignore)
│
├── pubspec.yaml                # Flutter dependencies & config
├── pubspec.lock                # Locked dependency versions
├── analysis_options.yaml       # Linter rules configuration
└── README.md                   # Project documentation

📦 Dependencies & Packages​

Core Framework​

  • flutter - Framework UI native
  • flutter_bloc ^8.0.0 - State management menggunakan BLoC pattern

HTTP & Networking​

  • dio ^5.3.3 - HTTP client modern dengan interceptor support
  • pretty_dio_logger ^1.1.1 - Logger untuk HTTP requests/responses
  • http ^1.1.0 - Alternative HTTP client

Local Storage & Database​

  • hive ^2.2.3 - NoSQL database untuk local storage
  • hive_flutter ^1.1.0 - Hive integration dengan Flutter
  • path_provider ^2.0.15 - Akses directory paths device
  • path ^1.8.2 - Path manipulation utilities

Camera & Scanning​

  • camera ^0.10.5+2 - Camera plugin untuk Flutter
  • flutter_barcode_scanner ^2.0.0 - Barcode scanner
  • mobile_scanner ^3.3.0 - Advanced QR/barcode scanner
  • image_picker ^1.0.1 - Image selection dari gallery/camera

UI Components & Widgets​

  • cupertino_icons ^1.0.5 - iOS-style icons
  • dropdown_button2 ^2.3.9 - Custom dropdown button
  • shimmer ^3.0.0 - Shimmer loading effect
  • liquid_progress_indicator_v2 ^0.5.0 - Animated progress indicator
  • card_swiper ^3.0.1 - Card swiper widget
  • webview_flutter ^4.2.3 - WebView untuk embedded web content

Utilities & Helpers​

  • equatable ^2.0.3 - Value equality untuk objects
  • intl ^0.18.1 - Internationalization & localization
  • rxdart ^0.27.7 - Reactive extensions untuk Dart
  • device_info_plus ^9.0.3 - Device information
  • logging ^1.1.1 - Logging utilities
  • fluttertoast ^8.2.1 - Toast notifications
  • image_compress ^2.0.4 - Image compression
  • stop_watch_timer ^3.0.1 - Stopwatch & timer

Development Dependencies​

  • flutter_test - Widget testing
  • hive_generator ^2.0.0 - Code generator untuk Hive models
  • flutter_lints ^2.0.1 - Linting rules
  • build_runner ^2.3.2 - Code generation runner
  • flutter_launcher_icons ^0.11.0 - Icon generator
  • mockito ^5.3.2 - Mocking untuk testing
  • http_mock_adapter ^0.6.0 - Mock HTTP adapter
  • flutter_app_name ^0.1.1 - App name configuration

🏗️ Arsitektur Project​

Project ini menggunakan Clean Architecture dengan BLoC Pattern untuk state management.

Layer Architecture​

Presentation Layer (UI)
    ↓
Business Logic Layer (BLoC)
    ↓
Data Layer (Repository)
    ├── Network (Dio API Client)
    └── Local (Hive Database)

BLoC Pattern​

Setiap fitur memiliki BLoC dengan struktur:

  • Event - Aksi/input dari user
  • State - Status saat ini
  • BLoC - Logic handler

Contoh:

// auth_bloc.dart
class AuthBloc extends Bloc<AuthEvent, AuthState> {
  // Handle login, logout, etc.
}

Repository Pattern​

Repository mengabstraksi data sources (API & local storage):

class LoginRepository {
  Future<UserModel> login(String email, String password);
  Future<void> saveToken(String token);
  Future<String?> getToken();
}

🚀 Setup & Environment​

Prerequisites​

  • Flutter SDK ≥ 3.0
  • Dart SDK ≥ 2.18.5
  • Android SDK (API 21 minimum)
  • Xcode (untuk iOS development)
  • Git untuk version control

Installation Steps​

  1. Clone Repository

    git clone <repository-url>
    cd simantra-flutter

  2. Get Flutter Dependencies

    flutter pub get

  3. Generate Hive Models (jika ada model hive)

    flutter pub run build_runner build

  4. Generate Icons

    flutter pub run flutter_launcher_icons:main

  5. Setup Android (jika diperlukan)

    cd android
    ./gradlew clean
    cd ..

  6. Setup iOS (jika diperlukan)

    cd ios
    pod install
    cd ..

🎮 Cara Menjalankan Project​

Development Mode​

# Run di device/emulator default
flutter run

# Run dengan flavor tertentu (jika ada)
flutter run --flavor production

# Run dengan debug verbose
flutter run -v

# Run di iOS
flutter run -d iphone

# Run di Android
flutter run -d android

Build APK (Android)​

# Debug APK
flutter build apk --debug

# Release APK
flutter build apk --release

# Split APK by ABI
flutter build apk --release --split-per-abi

Build iOS​

# Development build
flutter build ios --debug

# Release build
flutter build ios --release

✨ Fitur Utama​

1. Authentication (Login/Logout)​

  • BLoC: AuthBloc
  • Repository: LoginRepository
  • Pages: LoginPage, SplashPage
  • Features:
    • Login dengan email & password
    • Token management
    • Session persistence dengan Hive

2. Loading Process (Pengambilan Barang)​

  • BLoC: LoadingBloc
  • Repository: LoadingRepository
  • Pages: LoadingPage, ChecklistPage
  • Features:
    • Scan QR code produk
    • Manage item list
    • Checklist verification

3. Unloading Process (Pengeluaran Barang)​

  • BLoC: UnloadingBloc
  • Repository: UnloadingRepository
  • Pages: UnloadingPage, NCPage
  • Features:
    • Barcode scanning
    • Non-conformance (NC) handling
    • BAC (Batch Activity Check) verification

4. Security Checker​

  • BLoC: SecurityBloc
  • Repository: SecurityRepository
  • Pages: SecurityCheckerPage, ChecklistSecurityPage
  • Features:
    • Security scan process
    • Checklist validation
    • Document verification

5. Verificator/Supervisor​

  • BLoC: Integrated dengan loading & unloading
  • Pages: VerificatorPage, ScanVerificatorPage
  • Features:
    • Verify loading/unloading data
    • Final approval process

6. QR/Barcode Scanner​

  • Widget: QrScannerPage
  • Libraries: mobile_scanner, flutter_barcode_scanner
  • Features:
    • Real-time QR scanning
    • Barcode detection
    • Camera integration

💾 Database & Storage​

Hive (Local Database)​

  • Purpose: Menyimpan data local seperti user token, cached data
  • Setup: Dilakukan di InitHiveAdapter.dart dalam main() function
  • Models: Defined dengan @HiveType() annotation
// Inisialisasi di main.dart
await Hive.initFlutter();
initAdapter();  // Custom adapter initialization

Stored Data​

  • User authentication tokens
  • User session information
  • Cached API responses (optional)
  • Device information

Custom Hive Adapters​

Adapters didefinisikan di:

lib/core/InitHiveAdapter.dart

🔐 Authentication & Security​

Token Management​

  • BLoC: TokenBloc
  • Repository: TokenRepository
  • Storage: Hive database

Authentication Flow​

  1. User login → generate access token
  2. Token disimpan di Hive
  3. Token digunakan di setiap API request
  4. Token refresh mechanism (jika diperlukan)
  5. Logout → delete token dari Hive

Interceptor Security​

Dio interceptors menangani:

  • Menambahkan token ke header
  • Refresh token jika expired
  • Handle 401 unauthorized responses

🌐 API Integration​

HTTP Client Setup​

File: Network layer menggunakan Dio

// api_endpoints.dart
class ApiEndpoints {
  static const String baseUrl = 'https://api.example.com';
  static const String login = '/auth/login';
  static const String loading = '/loading';
  static const String unloading = '/unloading';
  // ... more endpoints
}

Request/Response Handling​

  • Request models di: lib/network_model/requests/
  • Response models di: lib/network_model/responses/

Error Handling​

  • Failed responses di-convert menjadi Failure objects
  • BLoC handle failures dan emit error states
  • UI display error messages dari failure

Logging​

  • pretty_dio_logger untuk development
  • Logs semua HTTP requests & responses
  • Disable di production untuk performance

🎛️ State Management (BLoC)​

BLoC Pattern Implementation​

class ScannerBloc extends Bloc<ScannerEvent, ScannerState> {
  ScannerBloc(this.repository) : super(ScannerInitial()) {
    on<ScanBarcodeEvent>(_onScanBarcode);
  }

  final ScannerRepository repository;

  Future<void> _onScanBarcode(
    ScanBarcodeEvent event,
    Emitter<ScannerState> emit,
  ) async {
    emit(ScannerLoading());
    try {
      final result = await repository.scanBarcode(event.barcode);
      emit(ScannerSuccess(result));
    } catch (e) {
      emit(ScannerFailure(e.toString()));
    }
  }
}

BLoCs di Project​

BLoCPurposeKey Responsibilities
AuthBlocAuthenticationLogin, logout, session management
LoadingBlocLoading processManage loading items & checklist
UnloadingBlocUnloading processManage unloading items & NC
ScannerBlocBarcode scanningQR code parsing & validation
SecurityBlocSecurity checksSecurity scan workflow
TokenBlocToken managementToken refresh & persistence
UserInfoBlocUser dataUser profile & permissions

💡 Tips untuk Developer Selanjutnya​

1. Before Making Changes​

  • Pahami BLoC architecture sebelum modifying
  • Check existing repository implementation
  • Review API models & endpoints

2. Code Structure Best Practices​

  • Satu feature = satu folder dengan BLoC, repo, pages
  • Keep business logic di BLoC, UI logic di pages
  • Use repositories untuk semua data access

3. Adding New Features​

Step-by-step:

1. Create data model (lib/model/)
2. Create API endpoint (lib/network/api_endpoints.dart)
3. Create network model (lib/network_model/)
4. Create repository (lib/repositories/)
5. Create BLoC events & states (lib/blocs/)
6. Create BLoC (lib/blocs/)
7. Create UI pages & widgets (lib/ui/)
8. Register BLoC di main.dart

4. Testing​

  • Unit test repositories & BLoCs
  • Use mockito untuk mocking API calls
  • Widget tests untuk critical UI components

5. Performance Optimization​

  • Cache API responses yang sering diakses
  • Use const untuk widgets yang static
  • Lazy load images menggunakan cached_network_image (jika ada)

6. Debugging Tips​

# Verbose logging
flutter run -v

# Check device logs
flutter logs

# Hot reload untuk development
Press 'r' untuk hot reload
Press 'R' untuk hot restart

7. Common Issues & Solutions​

IssueSolution
Hive model tidak generatedRun flutter pub run build_runner build
Icon tidak munculRun flutter pub run flutter_launcher_icons:main
BLoC states not emittingCheck if listener registered di UI
API 401 UnauthorizedCheck token validity & refresh mechanism
Camera permission deniedAdd permissions di AndroidManifest & Info.plist

🏗️ Build & Release​

Pre-Release Checklist​

  • Update version di pubspec.yaml
  • Test semua features di physical device
  • Check API endpoints (prod vs dev)
  • Remove debug prints
  • Test offline functionality
  • Update change logs

Android Release Build​

# Generate signed APK
flutter build apk --release \
  --target-platform android-arm64 \
  --suppress-analytics

# Generate App Bundle (for Play Store)
flutter build appbundle --release

Konfigurasi signing:

  • Create keystore: keytool -genkey -v -keystore ~/key.jks -keyalg RSA -keysize 2048 -validity 10000 -alias key
  • Update android/gradle.properties dengan keystore info
  • Update android/app/build.gradle dengan signing config

iOS Release Build​

# Build untuk physical device
flutter build ios --release

# Build untuk simulator
flutter build ios --release --simulator

# Create IPA untuk TestFlight/App Store
# Use Xcode atau Xcode Command Line Tools

🔧 Troubleshooting​

Issue: "Unable to load asset"​

Solution: Verify assets path di pubspec.yaml:

assets:
  - assets/images/
  - assets/fonts/

Issue: "BLoC not providing state"​

Solution: Ensure BLoC registered di BlocProvider:

BlocProvider(
  create: (context) => YourBloc(),
  child: YourPage(),
),

Issue: "Hive box not found"​

Solution: Initialize & register adapter sebelum akses:

await Hive.initFlutter();
initAdapter();
final box = await Hive.openBox('boxName');

Issue: "Camera permission denied"​

Solution: Add permissions ke native files:

AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs camera access for scanning</string>

Issue: "HTTP 401 Unauthorized"​

Solution: Check token mechanism di TokenRepository & Dio interceptor

Issue: "Dependency conflict"​

Solution: Update dependencies:

flutter pub get
flutter pub upgrade
flutter pub outdated

📜 Changelog​

Version 1.0.0 - Initial Release

  • Complete loading/unloading features
  • Security checker module
  • QR/Barcode scanning
  • Multi-user roles support

Last Updated: January 2026