PLC App

A Flutter application for the PLC community.

Prerequisites

• Flutter SDK 3.35.5 or higher
• Dart SDK 3.6.2 or higher
• Android Studio / Xcode (for mobile development)
• Google Sheets API service account credentials

Setup Instructions

1. Clone the Repository

git clone <repository-url>
cd plc

2. Install Dependencies

flutter pub get

3. Configure Google Sheets Credentials

The app uses envied for secure, obfuscated environment variables. You have several options to set this up:

Option A: Using the Setup Script (Recommended)

Run the interactive setup script:

./setup_credentials.sh

The script will guide you through:

• Importing from an existing service_account.json file
• Pasting the JSON content directly
• Creating from template for manual editing

Option B: Manual Setup

1. Copy the template file:

   cp .env.template .env

2. Edit .env and replace the placeholder JSON with your actual Google service account credentials

3. Save the file

Obtaining Service Account Credentials

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Sheets API
4. Go to "IAM & Admin" > "Service Accounts"
5. Create a new service account
6. Generate and download the JSON key
7. Share your Google Sheets with the service account email address

4. Generate Envied Code

After creating your .env file, generate the obfuscated environment code:

dart run build_runner build --delete-conflicting-outputs

This creates lib/core/config/env.g.dart with your encrypted credentials.

5. Running the App

Development Mode

flutter run

Building

Debug Build:

flutter build apk --debug

Release Build:

flutter build apk --release

Android App Bundle (for Play Store):

flutter build appbundle --release

6. Testing

flutter test

Release

Nada é publicado automaticamente. O bump de versão roda na sua máquina e o build é disparado à mão: o workflow Release é workflow_dispatch puro, sem gatilho por push ou por tag.

1. Deixe a main atualizada, com tudo mergeado e o working tree limpo. O lane aborta em ensure_git_status_clean se houver qualquer alteração pendente.

2. Rode o bump informando o nome da nova versão. O build number é incrementado sozinho (1.3.0+12 → 1.4.0+13):

   cd fastlane && bundle exec fastlane bump_version version:1.4.0

   O lane escreve a versão em pubspec.yaml, gera fastlane/metadata/android/pt-BR/changelogs/<build number>.txt com os commits desde a última tag, commita Bump version to 1.4.0+13 e cria a tag 1.4.0+13. Ele não faz push.

3. Revise o changelog gerado. Esse arquivo é o texto que aparece na Play Store.

4. Publique o commit e a tag:

   git push --follow-tags

5. Dispare o build:

   gh workflow run release.yaml

   Ou em Actions > Release > Run workflow.

O workflow compila o appbundle, publica na track beta e, depois que o environment android-production for aprovado, promove para produção.

O que entra no changelog

generate_changelog (em fastlane/actions/) pega os commits entre a última tag e o HEAD e mantém só os tipos feat:, fix:, perf: e security:, agrupados sob "Funcionalidades", "Correções de problemas", "Melhorias de Performance" e "Correções de Segurança".

O título do commit vira o item da lista. Quando o commit tem corpo, o corpo é publicado logo abaixo do título. Escreva esses commits para quem usa o app: nada de nome de arquivo, de função ou de decisão de implementação. O que for técnico vai em chore:, refactor:, test: ou docs:, que o gerador ignora.

Versões da toolchain

• Flutter: o CI usa flutter-version-file: pubspec.yaml, ou seja, o valor de environment.flutter. Rodar flutter pub get com outra versão reescreve o pubspec.lock e gera diff desnecessário.
• Ruby: o CI usa 3.1 (release.yaml), enquanto fastlane/mise.toml usa o latest da máquina. O Gemfile.lock versionado precisa continuar instalável nas duas versões.

Features

• Daily Reading (Liturgia Diária): View today's liturgical readings with liturgical color indicator
• Preachers: Browse community preachers and their information
• Secretary Documents: Access official documents and materials
• Parishes: Discover parishes with PLC presence
• About PLC: Learn about the Peregrinação de Leigos Cristãos movement

Project Structure

lib/
├── core/
│   ├── features/                          # Generic features library
│   │   ├── data/
│   │   │   ├── datasources/               # Generic data source implementations
│   │   │   ├── models/                    # Base model interfaces
│   │   │   └── repositories/              # Generic repository implementations
│   │   ├── domain/
│   │   │   ├── repositories/              # Repository interfaces
│   │   │   └── usecases/                  # Generic use cases
│   │   ├── presentation/
│   │   │   └── bloc/                      # Generic BLoC components
│   │   ├── core_features.dart             # Library exports
│   │   └── USAGE_EXAMPLE.md               # Detailed usage guide
│   └── storage/
│       ├── gsheets_storage_service.dart   # Google Sheets integration
│       └── local_storage_service.dart     # Local caching
├── features/                               # Feature modules
│   ├── preachers/                          # Preachers feature (old pattern)
│   └── secretary/                          # Secretary feature (new pattern)
└── main.dart                              # App entry point

Generic Features Library

This project includes a powerful Generic Features Library (lib/core/features/) that drastically reduces boilerplate when creating new read-only features.

Key Benefits

• ~70% less code per feature
• Automatic caching with 1-day sync by default
• Built-in search and filter support
• Type-safe generic implementations
• Google Sheets integration out of the box

Quick Start

Creating a new feature only requires:

1. Define Entity (domain/entities/your_entity.dart)
2. Define Model that extends EntityModel (data/models/your_model.dart)
3. Configure DI in injection_container.dart
4. Create UI using GenericListBloc

See lib/core/features/USAGE_EXAMPLE.md for detailed examples.

Example: Secretary Feature

The Secretary feature demonstrates the generic library usage. It was created with only:

• 3 files: Entity, Model, and UI page (~200 lines total)
• DI configuration: ~40 lines in injection_container.dart
• Full functionality: Caching, error handling, empty states, document opening

Compare this to the older Preachers feature which required ~15 files and ~800 lines of code!

CI/CD

The project uses GitHub Actions for continuous deployment:

• Builds are automatically created on workflow dispatch
• Deployment to Google Play Console (alpha, beta, production tracks)
• Credentials are injected securely via GitHub Secrets

Required GitHub Secrets

• GOOGLE_SERVICE_ACCOUNT: Google service account JSON (as a JSON string)
• ANDROID_KEYSTORE_BASE64: Base64-encoded Android keystore
• ANDROID_KEYSTORE_PASSWORD: Android keystore password
• GOOGLE_SERVICE_ACCOUNT_KEY: Google Play Console service account key

Security Notes

• Never commit .env - it's already in .gitignore
• Never commit service_account.json - keep credentials secure
• The app uses envied to obfuscate credentials at compile time
• Credentials are encrypted in the compiled binary (much more secure than --dart-define)
• The hardcoded credentials have been removed from the source code

How Envied Works

envied provides compile-time obfuscation and encryption of environment variables:

1. Compile-time encryption: When you run build_runner, envied encrypts your credentials
2. Obfuscated output: The generated env.g.dart contains encrypted values
3. Runtime decryption: The app decrypts values at runtime (very fast)
4. Binary protection: Much harder to extract credentials from the compiled app compared to --dart-define

Troubleshooting

"Google Service Account credentials not configured" Error

This means the app couldn't find the credentials. Make sure:

1. You've created the .env file
2. You've run dart run build_runner build --delete-conflicting-outputs
3. The env.g.dart file was generated successfully

"Target of URI hasn't been generated" Error

This means you need to run build_runner:

dart run build_runner build --delete-conflicting-outputs

Invalid JSON Format

Ensure your .env follows this structure:

GOOGLE_SERVICE_ACCOUNT={"type":"service_account","project_id":"..."}

Note: The service account JSON should be on a single line without quotes around it.

Resources

• Flutter Documentation
• Envied Package
• Google Sheets API
• Google Cloud Service Accounts