apksel-dev/apskel-owner-flutter
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
apskel-owner-flutter/README.md
efrilm 9775e09659 feat: readme
2025-08-22 15:26:16 +07:00

18 KiB
Raw Permalink Blame History

Apskel Owner Flutter

A POS (Point of Sale) application for business owners, built with Flutter. The project follows a layered architecture (presentation → application → domain → infrastructure) with dependency injection, state management, automated routing, internationalization, and code generation.

Contents

  • Technical Summary
  • Requirements & Setup
  • Running the App
  • Architecture Overview
  • Project Structure
  • Key Dependencies & Purpose
  • Code Generation
  • Internationalization (i18n)
  • Theming & Assets
  • Environment Configuration (env.dart)
  • Development Practices

Technical Summary

  • SDK: Flutter (Material) with Dart ^3.8.1
  • Targets: Android, iOS, Web, Desktop (Windows, macOS, Linux)
  • State management: flutter_bloc
  • Routing: auto_route
  • Dependency Injection: get_it + injectable
  • HTTP Client: dio (+ awesome_dio_interceptor)
  • Data class & serialization: freezed + json_serializable
  • Localization: flutter_localizations, l10n/*.arb
  • Assets generation: flutter_gen

Requirements & Setup

Prerequisites

  • Flutter SDK installed as per the official guide (https://flutter.dev/docs/get-started/install)
  • Dart version per constraint: ^3.8.1

Installation

git clone <your-repo-url>
cd apskel_owner_flutter
flutter pub get

Code generation (required after clone or when annotations change)

flutter pub run build_runner build --delete-conflicting-outputs

Re-run whenever you change files using @RoutePage(), @injectable, @freezed, or @JsonSerializable.

Running the App

flutter run

Select a specific device/platform:

flutter run -d chrome
flutter run -d ios
flutter run -d android

Example release builds:

flutter build apk --release
flutter build ios --release
flutter build web --release

Architecture Overview

The codebase follows a clean, layered approach that separates concerns and keeps features modular and testable:

  • Presentation (lib/presentation): Widgets, pages/screens, and the AutoRoute router. Contains only UI code and wiring to BLoC/Cubit.
  • Application (lib/application): BLoC/Cubit and application-level orchestration. Holds input validation, state transitions, and calls into the Domain layer.
  • Domain (lib/domain): Pure business logic. Entities, value objects, repository interfaces, and (optional) use-cases. No framework dependencies.
  • Infrastructure (lib/infrastructure): Repository implementations, DTOs, and data sources (HTTP/DB). Performs dio calls and mappings between DTOs and Domain entities.
  • Common (lib/common): Cross-cutting helpers such as API base, DI setup, constants, extensions, theme, validators, and utilities.

Data flow in a feature:

  1. UI triggers an intent/event in Presentation →
  2. Application layer BLoC/Cubit handles the event and calls a repository/use-case from Domain →
  3. Infrastructure implements the repository, performs network calls via dio, and maps results →
  4. Data is converted to Domain entities and returned to Application →
  5. Application updates state, Presentation rebuilds UI accordingly.

Cross-cutting concerns:

  • Dependency Injection: get_it + injectable auto-register services/repositories (injection.dart, injection.config.dart).
  • Routing: auto_route defines typed routes, generated into router files in presentation/router.
  • State: flutter_bloc models states/events and isolates side-effects in BLoCs/Cubits.
  • Networking: dio with interceptors for logging and error handling.
  • Error handling: functional style with dartz (Either, Option) or well-defined BLoC states.
  • i18n: ARB files in lib/l10n/ and generated localization delegates.
  • Theming: centralized theme under lib/common/theme/ with shared design tokens.
  • Assets: managed under assets/ and referenced via FlutterGen outputs at lib/presentation/components/assets/.

Project Structure

lib/
  application/           # BLoC/cubit per feature (analytic, auth, product, etc.)
  common/
    api/                 # Base API client, endpoint helper
    constant/            # Application constants
    di/                  # Dependency injection setup (get_it, injectable)
    extension/           # Extensions
    function/            # General utility functions
    network/             # Connectivity checks, handlers
    painter/             # Custom painters
    theme/               # Colors, text styles, theming
    url/                 # Base URL/endpoints
    utils/               # Other helpers
    validator/           # Input validators
  domain/
    <feature>/           # Entities, repo interfaces, (use-cases if present)
  infrastructure/
    <feature>/           # Repo implementations, DTOs, API calls
  l10n/                  # ARB sources for i18n + generated localizations
  presentation/
    components/          # Reusable widgets
    pages/               # Feature pages/screens
    router/              # AutoRoute definitions
  env.dart               # Environment configuration (BASE_URL, etc.)
  injection.dart         # DI entry point
  injection.config.dart  # DI generated
  main.dart              # Application entry point
assets/
  images/, icons/, json/, fonts/

Key Dependencies & Purpose

Runtime:

  • auto_route: Automated, typed routing based on annotations.
  • flutter_bloc: State management with BLoC/Cubit.
  • get_it, injectable: Service locator + codegen for DI.
  • dio, awesome_dio_interceptor: HTTP client + logging interceptor.
  • freezed_annotation, json_annotation: Annotations for immutable data classes & JSON.
  • dartz: Functional types (Either, Option) for explicit error handling.
  • connectivity_plus, device_info_plus, package_info_plus: Device and connectivity info.
  • shared_preferences: Local key-value storage.
  • image_picker, permission_handler, open_file, url_launcher: OS/device integrations.
  • UI: flutter_svg, line_icons, flutter_spinkit, fl_chart, another_flushbar, table_calendar, shimmer, cached_network_image, syncfusion_flutter_datepicker, pdf.

Dev:

  • build_runner: Code generation orchestration.
  • auto_route_generator, injectable_generator, freezed, json_serializable: Related generators.
  • flutter_gen_runner: Typed asset access generator.
  • flutter_lints: Recommended Flutter lints.
  • flutter_launcher_icons: Launcher icon generation.

Refer to pubspec.yaml for full version constraints.

Code Generation

Common commands:

flutter pub run build_runner build --delete-conflicting-outputs
# or watch
flutter pub run build_runner watch --delete-conflicting-outputs

Asset generation (flutter_gen_runner)

flutter_gen_runner is integrated with build_runner. Running the commands above will also generate typed accessors for assets based on the flutter_gen section in pubspec.yaml:

  • Output path: lib/presentation/components/assets/
  • SVG integration: enabled (flutter_svg: true)

Usage in code example (after generation):

// Example usage
// import 'presentation/components/assets/assets.gen.dart';
// Image.asset(Assets.images.logo.path);

Generators used:

  • AutoRoute: Generates router and typed routes.
  • Injectable: Generates DI registrations (injection.config.dart).
  • Freezed: Generates immutable data classes, copyWith, unions, etc.
  • Json Serializable: Generates toJson/fromJson for DTOs.
  • FlutterGen: Generates static asset access under lib/presentation/components/assets/.

Internationalization (i18n)

  • Source files live in lib/l10n/app_*.arb (e.g., app_en.arb, app_id.arb).
  • To add a language: create app_<code>.arb, then run code generation.
  • Ensure MaterialApp is wired with localizationsDelegates and supportedLocales (already prepared).

Theming & Assets

  • Theme files live under lib/common/theme/.
  • Fonts: Quicksand family is declared in pubspec.yaml.
  • Assets: assets/images/, assets/icons/, assets/json/ – referenced via FlutterGen outputs at lib/presentation/components/assets/.

Environment Configuration (env.dart)

The lib/env.dart file stores configuration values such as base URLs and debug flags. Adjust per environment (development/production) using flavors, environment variables, or branching as preferred by the team.

Development Practices

  • Routing: Define routes in presentation/router, then run code generation.
  • DI: Annotate services/repositories with @injectable/@LazySingleton, generate code, and call configureDependencies() early in app startup.
  • BLoC: Keep UI logic in the application layer and use BlocBuilder/BlocListener in the presentation layer.
  • DTO ↔ Entity: Mapping resides in the infrastructure layer to keep domain pure.
  • Error handling: Prefer Either/Option (dartz) or well-structured BLoC states.
  • Linting: Follow analysis_options.yaml.

Useful Commands

# Install dependencies
flutter pub get

# Format & Analyze
flutter format .
flutter analyze

# Code generation (single run / watch)
flutter pub run build_runner build --delete-conflicting-outputs
flutter pub run build_runner watch --delete-conflicting-outputs

# Run by device
flutter devices
flutter run -d <device-id>

Additional Notes

  • Launcher icons configured via launcher_icon.yaml.
  • Platform-specific configuration (Android/iOS/Web/Desktop) resides in respective platform folders.
  • Review analysis_options.yaml for code style and lint rules.

Launcher Icons

Configured via launcher_icon.yaml at the repository root. To (re)generate launcher icons, run:

dart run flutter_launcher_icons -f launcher_icon.yaml

If you prefer the Flutter shim:

flutter pub run flutter_launcher_icons -f launcher_icon.yaml

Ensure you have the package in dev_dependencies (flutter_launcher_icons).

Contributing

  1. Branch off main.
  2. Make focused changes and provide a clear PR description.
  3. Ensure build, lints, and codegen are clean before opening the PR.

License

This project is private/internal. Contact the repository owner for usage permissions.

Apskel Owner Flutter

Aplikasi Point of Sale (POS) untuk pemilik usaha, dibangun dengan Flutter. Proyek ini menerapkan arsitektur berlapis (presentation → application → domain → infrastructure) dengan dependency injection, state management, routing terotomasi, internationalization, dan code generation.

Isi Dokumen

  • Ringkasan Teknis
  • Persyaratan & Setup
  • Menjalankan Aplikasi
  • Arsitektur & Alur
  • Struktur Proyek
  • Dependensi Utama & Fungsinya
  • Code Generation
  • Internationalization (i18n)
  • Theming & Assets
  • Konfigurasi Lingkungan (env.dart)
  • Praktik Pengembangan

Ringkasan Teknis

  • SDK: Flutter (Material) dengan Dart ^3.8.1
  • Target platform: Android, iOS, Web, Desktop (Windows, macOS, Linux)
  • State management: flutter_bloc
  • Routing: auto_route
  • Dependency Injection: get_it + injectable
  • HTTP Client: dio (+ awesome_dio_interceptor)
  • Data class & serialization: freezed + json_serializable
  • Localization: flutter_localizations, l10n/*.arb
  • Assets generation: flutter_gen

Persyaratan & Setup

Prasyarat

  • Flutter SDK terpasang sesuai panduan resmi (https://flutter.dev/docs/get-started/install)
  • Versi Dart sesuai constraint: ^3.8.1

Instalasi

git clone <repo-url-anda>
cd apskel_owner_flutter
flutter pub get

Generate kode (wajib setelah clone atau mengubah anotasi)

flutter pub run build_runner build --delete-conflicting-outputs

Jalankan ulang perintah di atas setiap kali Anda mengubah file yang menggunakan anotasi @RoutePage(), @injectable, @freezed, atau @JsonSerializable.

Menjalankan Aplikasi

flutter run

Menentukan platform/target tertentu:

flutter run -d chrome
flutter run -d ios
flutter run -d android

Build release contoh:

flutter build apk --release
flutter build ios --release
flutter build web --release

Arsitektur & Alur

Proyek mengikuti layering yang jelas:

  • Presentation (lib/presentation): UI, widget, halaman, router.
  • Application (lib/application): BLoC/cubit, use-case orkestra ringan, validasi input UI.
  • Domain (lib/domain): Entitas, value object, repository interface, use-case (jika ada).
  • Infrastructure (lib/infrastructure): Implementasi repository, data source (API/DB), mapping DTO.
  • Common (lib/common): Utilitas umum, konstanta, theme, API base, DI bootstrap, extension, dll.

Alur umum:

  1. UI memicu event →
  2. BLoC di layer Application memanggil use-case/repo (Domain) →
  3. Implementasi repo (Infrastructure) melakukan HTTP via dio →
  4. Response dipetakan menjadi entity/domain →
  5. State di-update kembali ke UI.

Struktur Proyek

lib/
  application/           # BLoC/cubit per fitur (analytic, auth, product, dst.)
  common/
    api/                 # Base API client, endpoint helper
    constant/            # Konstanta aplikasi
    di/                  # Setup dependency injection (get_it, injectable)
    extension/           # Extension util
    function/            # Fungsi util umum
    network/             # Cek konektivitas, handler
    painter/             # Custom painter
    theme/               # Warna, text styles, theming
    url/                 # Base URL/endpoint
    utils/               # Helper lain
    validator/           # Validator input
  domain/
    <feature>/           # Entity, repo interface, (use-case bila ada)
  infrastructure/
    <feature>/           # Repo implementation, DTO, pemanggilan API
  l10n/                  # Berkas ARB untuk i18n + generated localizations
  presentation/
    components/          # Widget reusable
    pages/               # Halaman/layar fitur
    router/              # Definisi AutoRoute
  env.dart               # Konfigurasi environment (BASE_URL, dsb)
  injection.dart         # Entry point DI
  injection.config.dart  # DI generated
  main.dart              # Entrypoint aplikasi
assets/
  images/, icons/, json/, fonts/

Dependensi Utama & Fungsinya

Runtime:

  • auto_route: Routing terotomasi berbasis anotasi.
  • flutter_bloc: State management dengan BLoC/Cubit.
  • get_it, injectable: Service locator + codegen untuk DI.
  • dio, awesome_dio_interceptor: HTTP client + logging interceptor.
  • freezed_annotation, json_annotation: Anotasi untuk data class immutable & JSON.
  • dartz: Functional types (Either, Option) untuk error handling yang eksplisit.
  • connectivity_plus, device_info_plus, package_info_plus: Info perangkat & konektivitas.
  • shared_preferences: Penyimpanan key-value lokal.
  • image_picker, permission_handler, open_file, url_launcher: Integrasi perangkat/OS.
  • UI: flutter_svg, line_icons, flutter_spinkit, fl_chart, another_flushbar, table_calendar, shimmer, cached_network_image, syncfusion_flutter_datepicker, pdf.

Dev:

  • build_runner: Orkestrasi code generation.
  • auto_route_generator, injectable_generator, freezed, json_serializable: Generator terkait.
  • flutter_gen_runner: Generator akses asset terketik.
  • flutter_lints: Linter rekomendasi Flutter.
  • flutter_launcher_icons: Generate icon launcher.

Catatan versi lengkap tersedia di pubspec.yaml.

Code Generation

Perintah umum:

flutter pub run build_runner build --delete-conflicting-outputs
# atau untuk watch
flutter pub run build_runner watch --delete-conflicting-outputs

Generator yang digunakan:

  • AutoRoute: menghasilkan deklarasi router & route.
  • Injectable: menghasilkan registrasi DI (injection.config.dart).
  • Freezed: menghasilkan data class immutable, copyWith, union, dsb.
  • Json Serializable: menghasilkan toJson/fromJson untuk DTO.
  • FlutterGen: menghasilkan akses asset statis di lib/presentation/components/assets/.

Internationalization (i18n)

  • Berkas sumber ada di lib/l10n/app_*.arb (contoh: app_en.arb, app_id.arb).
  • Bahasa baru: tambahkan app_<kode>.arb, jalankan code generation.
  • Pastikan MaterialApp menggunakan localizationsDelegates dan supportedLocales (sudah disiapkan).

Theming & Assets

  • Theme ada di lib/common/theme/.
  • Font: keluarga Quicksand dideklarasikan di pubspec.yaml.
  • Assets: assets/images/, assets/icons/, assets/json/ – akses via FlutterGen yang dihasilkan ke lib/presentation/components/assets/.

Konfigurasi Lingkungan (env.dart)

File lib/env.dart menyimpan nilai konfigurasi seperti base URL, flag debug, dll. Sesuaikan untuk development/production (bisa dengan flavor, env var, atau branch khusus sesuai kebutuhan tim).

Praktik Pengembangan

  • Routing: definisikan route di presentation/router, jalankan codegen.
  • DI: daftarkan service/repository dengan anotasi @injectable/@LazySingleton, lalu generate, dan panggil configureDependencies() di awal aplikasi.
  • BLoC: simpan logic UI di layer application dan gunakan BlocBuilder/BlocListener di layer presentation.
  • DTO ↔ Entity: mapping berada di layer infrastructure untuk menjaga domain tetap bersih.
  • Error handling: gunakan Either/Option (dartz) atau state terstruktur di BLoC.
  • Lint: patuhi aturan analysis_options.yaml.

Perintah Berguna

# Install dependencies
flutter pub get

# Format & Analyze
flutter format .
flutter analyze

# Code generation (sekali jalan / watch)
flutter pub run build_runner build --delete-conflicting-outputs
flutter pub run build_runner watch --delete-conflicting-outputs

# Run by device
flutter devices
flutter run -d <device-id>

Catatan Tambahan

  • Icon launcher dikonfigurasi di launcher_icon.yaml (gunakan flutter pub run flutter_launcher_icons bila diperlukan).
  • Konfigurasi platform (Android/iOS/Web/Desktop) berada pada folder platform terkait.
  • Pastikan meninjau analysis_options.yaml untuk standar code style dan lints.

Kontribusi

  1. Buat branch dari main.
  2. Lakukan perubahan terfokus dan sertakan deskripsi yang jelas pada PR.
  3. Pastikan build, lints, dan codegen bersih sebelum mengajukan PR.

Lisensi

Proyek ini bersifat privat/internal. Hubungi pemilik repositori untuk detail izin penggunaan.