Comprehensive pwE Documentation

Project Principles and Pillars

Developed under strict architectural and design standards (as defined in the official theme in app_theme.dart), pwE is sustained by three fundamental pillars:

Architectural Layers

The separation of concerns ensures ease of maintenance and high coverage of unit tests:

• Domain Layer (Domain): Contains pure business rules (Entities, UseCases, and defined contracts). See the Lectio Divina entity in the file lectio_session.dart:
  Copiar

  // lib/features/lectio_divina/domain/entities/lectio_session.dart
  class LectioSession {
    final String id;
    final DateTime date;
    final String passage;
    final String emotion;
    final String meditation;
    final String prayer;
    final String contemplationResolution;
    final int streakDays;
  
    const LectioSession({
      required this.id,
      required this.date,
      required this.passage,
      required this.emotion,
      required this.meditation,
      required this.prayer,
      required this.contemplationResolution,
      required this.streakDays,
    });
  }

• Data Layer (Data): Contains the infrastructure (Models, DataSources, and concrete repository implementations as in llm_remote_datasource.dart):
  Copiar

  // lib/features/lectio_divina/data/datasources/llm_remote_datasource.dart
  abstract class LlmRemoteDataSource {
    Future<MeditationModel> generateMeditation(MeditationRequestModel request);
  }
  
  class LlmRemoteDataSourceImpl implements LlmRemoteDataSource {
    final ApiClient apiClient;
  
    LlmRemoteDataSourceImpl({required this.apiClient});
  
    @override
    Future<MeditationModel> generateMeditation(MeditationRequestModel request) async {
      final response = await apiClient.post(
        '/v1/spiritual-advisor/meditate',
        data: request.toJson(),
      );
      return MeditationModel.fromJson(response.data);
    }
  }

• Presentation Layer (Presentation): Contains the user interface (Widgets and Pages) and complex state management based on **Bloc** (see in lectio_bloc.dart):
  Copiar

  // lib/features/lectio_divina/presentation/bloc/lectio_bloc.dart
  class LectioBloc extends Bloc<LectioEvent, LectioState> {
    final GetGuidedMeditation getGuidedMeditation;
    final SaveSession saveSession;
  
    LectioBloc({
      required this.getGuidedMeditation,
      required this.saveSession,
    }) : super(LectioInitial()) {
      on<StartSessionEvent>(_onStartSession);
      on<AdvanceToStepEvent>(_onAdvanceToStep);
      on<CompleteSessionEvent>(_onCompleteSession);
    }
  
    void _onStartSession(StartSessionEvent event, Emitter<LectioState> emit) {
      emit(LectioInProgress(step: LectioStep.reading, passage: event.passage));
    }
  }

Focused UI Components

These UI elements create an atmosphere of introspection in the page immersive_reading_page.dart:

• ProgressiveTextReveal: Hides future segments using blur until the user scrolls or interacts with the text, helping them focus on the current reading.
• HoldToSaveButton: Requires pressing the button for 2 continuous seconds with haptic feedback to ensure intent to advance steps, preventing accidental clicks in the silence of prayer.
• ThinkingFeedback: Displays rotating motivational and spiritual messages while the AI processes the prompt (e.g., "Uniting your prayer to the heavenly choirs...").

Veja um exemplo prático de implementação do HoldToSaveButton, com lógica tátil e preenchimento gradual por tempo em Flutter:

// lib/features/lectio_divina/presentation/widgets/hold_to_save_button.dart
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

class HoldToSaveButton extends StatefulWidget {
  final VoidCallback onTrigger;
  final String label;

  const HoldToSaveButton({Key? key, required this.onTrigger, required this.label}) : super(key: key);

  @override
  _HoldToSaveButtonState createState() => _HoldToSaveButtonState();
}

class _HoldToSaveButtonState extends State<HoldToSaveButton> with SingleTickerProviderStateMixin {
  late AnimationController _controller;

  @override
  void initState() {
    super.initState();
    _controller = AnimationController(
      vsync: this,
      duration: const Duration(seconds: 2),
    );
    _controller.addStatusListener((status) {
      if (status == AnimationStatus.completed) {
        HapticFeedback.heavyImpact();
        widget.onTrigger();
        _controller.reset();
      }
    });
  }

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return GestureDetector(
      onLongPressStart: (_) {
        HapticFeedback.mediumImpact();
        _controller.forward();
      },
      onLongPressEnd: (_) {
        if (_controller.status != AnimationStatus.completed) {
          _controller.reverse();
        }
      },
      child: AnimatedBuilder(
        animation: _controller,
        builder: (context, child) {
          return Container(
            height: 56,
            width: double.infinity,
            decoration: BoxDecoration(
              borderRadius: BorderRadius.circular(12),
              border: Border.all(color: Colors.amber.shade700, width: 1.5),
              gradient: LinearGradient(
                colors: [Colors.amber.shade800, Colors.amber.shade900],
                stops: [0.0, _controller.value],
              ),
            ),
            child: Center(
              child: Text(
                _controller.value > 0 ? 'Mantenha pressionado... ${(_controller.value * 100).toInt()}%' : widget.label,
                style: const TextStyle(fontWeight: FontWeight.bold, color: Colors.white),
              ),
            ),
          );
        },
      ),
    );
  }
}

The Three Stages of Maturity

Local Inference Technical Specifications

• Model Used: Gemma 4 (2B class) optimized and quantized for mobile devices.
• Engine: Based on the **LiteRT-LM** library running on fast and efficient native method channels (`MethodChannel`). Managed by llm_local_datasource.dart.
• Minimum Hardware: Smartphones with 4GB of free RAM, GPU/NPU graphics acceleration support, and ~1.3GB of free space for the quantized model.
• Privacy Visual Indicator: Whenever the AI is processed locally, the app displays a Golden Shield, certifying the isolation of the processing.

Below is the practical implementation of LlmLocalDataSourceImpl, demonstrating native invocation and automatic fallback to the cloud in case of error:

// lib/features/lectio_divina/data/datasources/llm_local_datasource.dart
import 'package:flutter/services.dart';
import 'package:pwe/features/lectio_divina/data/models/meditation_model.dart';
import 'package:pwe/features/lectio_divina/data/models/meditation_request_model.dart';
import 'package:pwe/features/lectio_divina/data/datasources/llm_remote_datasource.dart';

abstract class LlmLocalDataSource {
  Future<MeditationModel> generateMeditation(MeditationRequestModel request);
}

class LlmLocalDataSourceImpl implements LlmLocalDataSource {
  static const MethodChannel _channel = MethodChannel('pwe.app/gemma-inference');
  final LlmRemoteDataSource remoteFallback;
  final bool isGemmaEnabled;

  LlmLocalDataSourceImpl({
    required this.remoteFallback,
    required this.isGemmaEnabled,
  });

  @override
  Future<MeditationModel> generateMeditation(MeditationRequestModel request) async {
    if (!isGemmaEnabled) {
      return remoteFallback.generateMeditation(request);
    }

    try {
      final String? response = await _channel.invokeMethod<String>(
        'executeGemmaInference',
        {
          'prompt': request.toPrompt(),
          'max_tokens': 200,
          'temperature': 0.3,
        },
      );

      if (response == null || response.isEmpty) {
        throw PlatformException(code: 'EMPTY_RESPONSE', message: 'Gemma local retornou vazio.');
      }

      return MeditationModel.fromLocalText(response, request.passage);
    } catch (e) {
      // Fallback transparente em caso de indisponibilidade ou falha de inferência local
      return remoteFallback.generateMeditation(request);
    }
  }
}

OCR Architecture & Mechanics

Integrating **Google ML Kit Vision**, the process is entirely offline and agile:

Below is the practical example of integration with the ML Kit OCR for offline extraction of biblical text from physical pages of the Bible:

// lib/features/lectio_divina/data/datasources/ocr_local_datasource.dart
import 'dart:io';
import 'package:google_ml_kit/google_ml_kit.dart';

abstract class OcrLocalDataSource {
  Future<String> extractTextFromImage(File imageFile);
}

class OcrLocalDataSourceImpl implements OcrLocalDataSource {
  final TextRecognizer _textRecognizer = GoogleMlKit.vision.textRecognizer();

  @override
  Future<String> extractTextFromImage(File imageFile) async {
    final inputImage = InputImage.fromFile(imageFile);
    try {
      final RecognizedText recognizedText = await _textRecognizer.processImage(inputImage);
      
      // Filtra e limpa o texto para remover ruídos e marcas indesejadas do reconhecimento
      String rawText = recognizedText.text;
      return _refineBiblicalText(rawText);
    } catch (e) {
      throw Exception('Erro ao processar imagem via ML Kit OCR: ${e.toString()}');
    }
  }

  String _refineBiblicalText(String input) {
    return input
        .replaceAll('\n', ' ')
        .replaceAll(RegExp(r'\s+'), ' ')
        .trim();
  }

  void dispose() {
    _textRecognizer.close();
  }
}

Árvore de Pastas

lib/
├── core/                        # Shared Core
│   ├── di/                      # GetIt Container (injection_container.dart)
│   ├── error/                   # Failures and Exceptions (Either)
│   ├── network/                 # REST Clients and network configurations
│   ├── routes/                  # Route configurations with GoRouter
│   └── theme/                   # Visual styles and app palettes
├── features/                    # Isolated domain modules
│   ├── lectio_divina/           # Main domain of Prayerful Reading
│   │   ├── data/                # DTOs, Repositories, and data sources
│   │   ├── domain/              # Entities, business rules, and UseCases
│   │   └── presentation/        # BLoC controllers, widgets, and pages
│   ├── auth/                    # Login and security management
│   └── profile/                 # Maturity control and preferences
└── main.dart                    # App configurations and bootstrap