From f32bbc363c958921a95be2793dcaba12e4b77022 Mon Sep 17 00:00:00 2001 From: Olga Shen Date: Mon, 4 Aug 2025 13:28:37 +0800 Subject: [PATCH] docs: improve development documentation - Add CLAUDE.md with comprehensive development guide for AI assistants - Add DEPLOYMENT.md with detailed deployment workflow documentation - Add .github/copilot-instructions.md for GitHub Copilot guidance - Update README.md with improved setup instructions and realistic development flow - Modernize GitHub Actions workflows: - Replace tag-based triggers with workflow_dispatch for better UX - Add platform selection options for firebase-release (Android/iOS) - Remove deprecated Slack notifications from build and pre-release workflows - Streamline build-apks.yml with manual trigger support - Update Android build configuration for improved compatibility --- .github/copilot-instructions.md | 143 ++++++++++++++ .github/workflows/build-apks.yml | 9 +- .github/workflows/build.yml | 30 --- .github/workflows/firebase-release.yml | 21 +- .github/workflows/pre-release.yml | 28 --- CLAUDE.md | 150 +++++++++++++++ DEPLOYMENT.md | 253 +++++++++++++++++++++++++ README.md | 139 ++++++++------ android/build.gradle | 2 +- android/variables.gradle | 4 +- 10 files changed, 658 insertions(+), 121 deletions(-) create mode 100644 .github/copilot-instructions.md create mode 100644 CLAUDE.md create mode 100644 DEPLOYMENT.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..32c846cf7 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,143 @@ +# Capture Lite - GitHub Copilot Instructions + +## Project Overview + +This is the **capture-lite** repository - an Angular/Ionic mobile application that serves as the Capture Cam mobile app for creator-focused content monetization. It's a cross-platform mobile app (iOS and Android) built with Angular 14, Ionic 6, and Capacitor 7. + +The app enables users to capture media with provenance tracking, connect to blockchain networks for content verification, and manage digital assets with built-in cryptocurrency wallet functionality. + +## Technology Stack + +- **Frontend Framework**: Angular 14 with TypeScript +- **Mobile Framework**: Ionic 6 with Capacitor 7 +- **State Management**: NgRx Store +- **UI Components**: Angular Material + Ionic components +- **Internationalization**: Transloco +- **Testing**: Karma/Jasmine (unit tests) +- **Build System**: Angular CLI with Ionic CLI +- **Package Manager**: NPM with `--legacy-peer-deps` flag required + +## Project Structure + +### Core Directories + +- `src/app/features/`: Feature modules (lazy-loaded) - home, login, settings, wallets, contacts, activities +- `src/app/shared/`: Shared services, components, and utilities +- `src/assets/`: Static assets including fonts, i18n files, and images +- `src/environments/`: Environment-specific configurations +- `android/`: Android platform files (Capacitor) +- `ios/`: iOS platform files (Capacitor) + +### Key Services Architecture + +- `shared/dia-backend/`: Backend API integration services +- `shared/capture/`: Core media capture and proof generation +- `shared/collector/`: Metadata collection with facts and signature providers +- `shared/database/`: Local storage abstraction using Capacitor filesystem +- `shared/camera/`: Capacitor camera integration +- `shared/media/`: Media display and storage management + +## Development Commands + +### Setup and Development + +```bash +npm install --legacy-peer-deps # Required for dependency compatibility +npm run serve # Start development server +npm run serve.prod # Start dev server with production config +``` + +### Building + +```bash +npm run build # Build for production +npm run build.android # Build and sync for Android +npm run build.ios # Build and sync for iOS +``` + +### Testing and Quality + +```bash +npm run test # Run unit tests +npm run test.ci # Run tests in headless CI mode +npm run lint # Run linting (required before commit) +``` + +### Platform Commands + +```bash +npx cap sync android # Sync web assets to Android +npx cap sync ios # Sync web assets to iOS +npx cap open android # Open in Android Studio +npx cap open ios # Open in Xcode +``` + +## Development Guidelines + +### Code Quality Standards + +- Always run `npm run lint` before committing +- Use Prettier for code formatting (configured with pre-commit hooks) +- Follow Angular style guide and conventions +- Maintain comprehensive test coverage with Karma/Jasmine +- Use Visual Studio Code with Prettier extension enabled + +### TypeScript Patterns + +- Prefer `Promise` over `Observable` for single-value emissions +- Avoid `toPromise()` - use `firstValueFrom()` instead +- Use strict TypeScript configuration +- Implement proper type safety throughout + +### Architecture Patterns + +- **Feature Modules**: Organize code by features with lazy loading +- **Repository Pattern**: Use for data access abstraction +- **Provider Pattern**: Implement pluggable components (FactsProvider, SignatureProvider) +- **Service Layer**: Centralize business logic in services +- **Component Architecture**: Feature-based modules with shared components + +### Mobile Development Considerations + +- Use Capacitor plugins for native device APIs +- Handle platform-specific behavior (especially Android) +- Implement offline support with local database sync +- Optimize performance with lazy loading and asset optimization +- Follow mobile-first responsive design principles + +## Configuration Files + +- `capacitor.config.json`: Native app configuration and plugin settings +- `ionic.config.json`: Ionic CLI configuration +- `angular.json`: Angular build and test configurations +- `package.json`: Dependencies and scripts +- Environment files in `src/environments/` + +## Testing Strategy + +- Unit tests with Karma + Jasmine + ChromeHeadless +- Mock services available in `shared/capacitor-plugins/` +- Separate testing modules for shared functionality +- CI/CD integration with GitHub Actions + +## Deployment Notes + +- Local development has limited functionality due to missing environment configs +- Use GitHub Actions for full testing (Android APK Build, Firebase Release) +- Development workflow: Local changes → GitHub Actions deployment → Device testing +- Production releases managed through Play Store (alpha) and TestFlight + +## Common Issues + +- Always use `npm install --legacy-peer-deps` for dependency installation +- Environment-specific configurations may cause local limitations +- Performance considerations due to raw file system usage for proofs +- Platform-specific setup required for Android Studio path on Linux + +## Key Dependencies + +- Angular 14, Ionic 6, Capacitor 7 +- NgRx for state management +- Angular Material for UI components +- Transloco for internationalization +- Various Capacitor plugins for native functionality diff --git a/.github/workflows/build-apks.yml b/.github/workflows/build-apks.yml index 9fc0cdc5f..236cdfd7a 100644 --- a/.github/workflows/build-apks.yml +++ b/.github/workflows/build-apks.yml @@ -1,9 +1,12 @@ name: Build APKs on: - push: - tags: - - 'android-*' + workflow_dispatch: + inputs: + description: + description: 'Build description (optional)' + required: false + type: string jobs: build-apks-upload-google-drive: diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 2d0a4dcd0..897023bf6 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -117,33 +117,3 @@ jobs: sed -i '' "s/\$(GOOGLE_IOS_URL_SCHEME)/${GOOGLE_IOS_URL_SCHEME}/g" ios/App/App/info.plist npx cap sync ios xcodebuild archive -workspace ios/App/App.xcworkspace -scheme App -sdk iphoneos -configuration Debug -archivePath build/App.xcarchive -showBuildTimingSummary -allowProvisioningUpdates archive - - notification-success: - runs-on: ubuntu-latest - if: github.actor != 'dependabot[bot]' - needs: [android, ios] - - steps: - - uses: actions/checkout@v4 - - - name: Slack Notification - uses: rtCamp/action-slack-notify@v2 - if: ${{ github.ref == 'refs/heads/main' || github.event.pull_request.base.ref == 'main'}} - env: - SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} - SLACK_COLOR: 'success' - - notification-failure: - runs-on: ubuntu-latest - needs: [android, ios] - if: ${{ failure() && github.actor != 'dependabot[bot]'}} - - steps: - - uses: actions/checkout@v4 - - - name: Slack Notification - uses: rtCamp/action-slack-notify@v2 - if: ${{ github.ref == 'refs/heads/main' || github.event.pull_request.base.ref == 'main'}} - env: - SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} - SLACK_COLOR: 'failure' diff --git a/.github/workflows/firebase-release.yml b/.github/workflows/firebase-release.yml index e40b7f5e4..73671e286 100644 --- a/.github/workflows/firebase-release.yml +++ b/.github/workflows/firebase-release.yml @@ -1,14 +1,28 @@ name: firebase-release on: - push: - tags: - - 'firebase-*' + workflow_dispatch: + inputs: + android: + description: 'Build Android' + required: false + default: true + type: boolean + ios: + description: 'Build iOS' + required: false + default: true + type: boolean + description: + description: 'Build description (optional)' + required: false + type: string jobs: distribute-android: runs-on: ubuntu-latest timeout-minutes: 120 + if: ${{ inputs.android }} steps: - uses: actions/checkout@v4 @@ -73,6 +87,7 @@ jobs: distribute-ios: runs-on: macos-15 timeout-minutes: 120 + if: ${{ inputs.ios }} steps: - uses: actions/checkout@v4 diff --git a/.github/workflows/pre-release.yml b/.github/workflows/pre-release.yml index b069d873f..a4ae3f8f4 100644 --- a/.github/workflows/pre-release.yml +++ b/.github/workflows/pre-release.yml @@ -313,31 +313,3 @@ jobs: with: body: Thanks for following along! For more information check out the [CHANGELOG](https://github.com/numbersprotocol/capture-lite/blob/main/CHANGELOG.md). prerelease: true - - - name: Send Slack notification - uses: rtCamp/action-slack-notify@master - env: - SLACK_WEBHOOK: ${{ secrets.SLACK_WEBHOOK }} - SLACK_CHANNEL: reminder-releases - SLACK_COLOR: '#6EE4D3' - SLACK_ICON: https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png - SLACK_MESSAGE: | - Version: ${{ steps.version_check.outputs.version }} - - - APKs - - - - - - - iOS Testflight - - Build: ${{ env.ios_build_number }} - A push notification will be sent to the device with TestFlight installed when the build is ready. - - Notes - - - Publishing process usually requires some time to complete, and thus the link provided above might still display the old version of the app. Please check the app version before download and install the app. - - This message is automatically sent from GitHub Action. - SLACK_TITLE: Capture Lite QA Release - SLACK_USERNAME: GitHub Action diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..f32ef3ee9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,150 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Repository Overview + +This is the **capture-lite** repository - an Angular/Ionic mobile application that serves as the Capture Cam mobile app for creator-focused content monetization. It's a mobile app that runs on iOS and Android platforms, built with Angular 14, Ionic 6, and Capacitor 7. + +The app enables users to capture media with provenance tracking, connect to blockchain networks for content verification, and manage digital assets with built-in cryptocurrency wallet functionality. + +## Development Commands + +### Setup and Development + +```bash +npm install --legacy-peer-deps # Install dependencies (required for compatibility) +npm run serve # Start development server (includes preconfig) +npm run serve.prod # Start dev server with production config +``` + +### Building + +```bash +npm run build # Build for production (includes preconfig) +npm run build.android # Build and sync for Android +npm run build.ios # Build and sync for iOS +``` + +### Testing and Quality + +```bash +npm run test # Run unit tests with Karma/Jasmine +npm run test.ci # Run tests in headless CI mode +npm run lint # Run linting (Prettier, Stylelint, ESLint) +``` + +### Platform-Specific Commands + +```bash +npx cap sync android # Sync web assets to Android +npx cap sync ios # Sync web assets to iOS +npx cap open android # Open project in Android Studio +npx cap open ios # Open project in Xcode +``` + +## Architecture Overview + +### Core Technology Stack + +- **Frontend Framework**: Angular 14 with TypeScript +- **Mobile Framework**: Ionic 6 with Capacitor 7 +- **State Management**: NgRx Store for component state +- **UI Components**: Angular Material + Ionic components +- **Internationalization**: Transloco for multi-language support +- **Testing**: Karma/Jasmine (unit tests) + +### Application Structure + +#### Feature Modules (Lazy-loaded) + +- **home/**: Main application interface with capture, collection, and post-capture tabs +- **login/signup/**: Authentication flows with social login support +- **settings/**: User preferences, email verification, GoPro integration +- **wallets/**: Cryptocurrency wallet management and NUM token transfers +- **contacts/**: Friend management and sharing functionality +- **activities/**: Transaction history and capture details + +#### Shared Services Architecture + +- **dia-backend/**: Backend API integration services + - Asset management (uploading, downloading, prefetching) + - Authentication and user management + - Blockchain transaction handling + - Series and workflow management +- **capture/**: Core media capture and proof generation +- **collector/**: Metadata collection with facts and signature providers +- **database/**: Local storage abstraction using Capacitor filesystem +- **camera/**: Capacitor camera integration +- **media/**: Media display and storage management + +### Data Flow Pattern + +1. **Media Capture**: Camera service → Capture service → Proof generation +2. **Backend Sync**: Local storage → DIA Backend services → Blockchain +3. **State Management**: Services → NgRx store → Components +4. **Cross-platform**: Capacitor plugins → Native device APIs + +## Configuration Files + +- **capacitor.config.json**: Native app configuration and plugin settings +- **ionic.config.json**: Ionic CLI configuration +- **angular.json**: Angular build and test configurations +- **environments/**: Environment-specific configurations + +## Testing Strategy + +### Unit Testing + +- **Framework**: Karma + Jasmine with ChromeHeadless +- **Coverage**: Cobertura reports generated +- **Mock Services**: Comprehensive mocking in `shared/capacitor-plugins/` +- **Testing Modules**: Separate testing modules for shared functionality + +## Key Development Patterns + +### Service Organization + +- **Repository Pattern**: Data access abstraction (e.g., ProofRepository) +- **Provider Pattern**: Pluggable implementations (FactsProvider, SignatureProvider) +- **Backend Abstraction**: DIA Backend services centralize API calls +- **Preference Management**: Unified settings storage with Capacitor Preferences + +### Component Architecture + +- **Feature-based Modules**: Each feature has its own routing and module +- **Shared Components**: Reusable UI components in shared/ +- **Tab-based Navigation**: Main interface uses Ionic tabs +- **Modal Dialogs**: Angular Material dialogs for overlays + +### Mobile-First Considerations + +- **Capacitor Integration**: Native device APIs through plugins +- **Platform Detection**: Android-specific behavior handling +- **Offline Support**: Local database with sync capabilities +- **Performance**: Lazy loading modules and asset optimization + +## Code Quality Standards + +### Linting and Formatting + +- **Prettier**: Code formatting with pre-commit hooks +- **ESLint**: Angular-specific linting rules +- **Stylelint**: SCSS/CSS linting +- **Husky**: Git hooks for automated quality checks + +### TypeScript Configuration + +- **Strict Mode**: Enabled with strict injection parameters +- **Path Mapping**: Browser API polyfills configured +- **Module Resolution**: Node.js-style resolution + +### Development Guidelines + +- Prefer Promise over Observable for single-value emissions +- Avoid `toPromise()` conversion (use `firstValueFrom` instead) +- Use Visual Studio Code with Prettier extension +- Run `npm run lint` before commits +- Maintain comprehensive test coverage + +This mobile application combines modern web technologies with native mobile capabilities to create a content authenticity and blockchain integration platform. diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md new file mode 100644 index 000000000..b2694d3f6 --- /dev/null +++ b/DEPLOYMENT.md @@ -0,0 +1,253 @@ +# Deployment Guide + +This document provides step-by-step instructions for the development and deployment workflow for the Capture Cam app. + +## Development Workflow Overview + +Due to local environment limitations (missing environment-specific configurations), the recommended development flow is: + +1. **Develop & Test Locally**: Make code changes, ensure build and tests pass +2. **Deploy for Testing**: Use GitHub Actions to build and test your changes +3. **Verify Implementation**: Test the actual app functionality through deployed builds +4. **Code Review**: Request senior developer review after confirming changes work as expected +5. **Release**: Proceed to QA/production deployment after approval + +## Available Deployment Options + +The app supports three GitHub Action deployment types: + +- **Android APK Build**: Generate APK files for direct installation and testing +- **Firebase Release**: Distribute Android AAB and iOS IPA to test groups via Firebase App Distribution +- **Pre-release (Store Release)**: Deploy to Google Play Store (alpha) and Apple TestFlight (for official QA/production only) + +## Development Testing Deployment + +### Step 1: Choose Your Testing Method + +**For Feature Development & Bug Fixes:** + +- **Android APK Build**: Best for quick Android testing with APK files +- **Firebase Release**: Best for distributing to test groups (both Android AAB and iOS IPA) + +**Recommendation**: Use **Firebase Release** for most development testing as it provides both Android and iOS builds distributed to your test groups with full environment configuration. + +### Step 2: Trigger GitHub Action for Development Testing + +**For Android APK Build:** + +1. **Commit, Push, and Create PR**: + + ```bash + git add . + git commit -m "feat: implement [your feature description]" + git push origin [your-feature-branch] + ``` + + - Create a Pull Request on GitHub + +2. **Trigger via GitHub Actions UI**: + - Visit [GitHub Actions tab](https://github.com/numbersprotocol/capture-lite/actions) + - Select "Build APKs" workflow + - Click "Run workflow", select your branch + - Optionally add a description and click "Run workflow" + +**For Firebase Release:** + +1. **Increment Android Version Code** (if building Android): + + ```gradle + // In android/app/build.gradle - only needed if building Android + android { + defaultConfig { + versionCode 1011 // e.g., 1010 → 1011 (small increment for testing) + versionName "0.101.0" // Keep current version + } + } + ``` + +2. **Commit, Push, and Create PR**: + + ```bash + git add android/app/build.gradle # only if modified + git commit -m "chore: increment versionCode for Firebase testing" + git push origin [your-feature-branch] + ``` + + - Create a Pull Request on GitHub (if not already created) + +3. **Trigger via GitHub Actions UI**: + - Visit [GitHub Actions tab](https://github.com/numbersprotocol/capture-lite/actions) + - Select "firebase-release" workflow + - Click "Run workflow", select your branch + - Choose platforms: Check "Build Android" and/or "Build iOS" (both selected by default) + - Optionally add a description and click "Run workflow" + +**Note**: Firebase Release automatically handles iOS versioning with timestamps, but Android uses the static `versionCode` from gradle file. + +### Step 3: Test Your Implementation + +**Android APK Build:** + +- Download the generated APK from the GitHub Actions artifacts +- Install on Android device/emulator for testing +- Verify your feature/fix works as expected + +**Firebase Release:** + +- Builds are automatically distributed to Firebase App Distribution test groups +- Testers receive notifications to download Android AAB and iOS IPA files +- Test on both Android and iOS devices with full functionality +- Access through Firebase App Distribution app or email links + +### Step 4: Code Review Process + +Once you've verified your changes work correctly: + +**Add senior developers as reviewers** to your existing Pull Request + +## QA/Production Deployment + +After code review approval, proceed with official QA deployment: + +### Step 1: Bump Version Numbers + +**Important**: Always bump the version before deployment to ensure users can see the new version. + +You need to update **4 files** with the new version number: + +#### 1. Update package.json + +```json +{ + "version": "0.102.0" +} +``` + +#### 2. Update Android version in android/app/build.gradle + +```gradle +android { + defaultConfig { + versionCode 1020 // e.g., 1010 → 1020 + versionName "0.102.0" // e.g., 0.101.0 → 0.102.0 + } +} +``` + +#### 3. Update iOS version in ios/App/App.xcodeproj/project.pbxproj + +Update both occurrences of: + +``` +CURRENT_PROJECT_VERSION = 1020; // e.g., 1010 → 1020 +MARKETING_VERSION = 0.102.0; // e.g., 0.101.0 → 0.102.0 +``` + +#### 4. Update CHANGELOG.md + +Add a new release section with: + +- Release date +- Added features +- Changed functionality +- Fixed bugs +- Update the comparison links at the bottom + +#### 5. Update package-lock.json + +```bash +npm install --legacy-peer-deps +``` + +**Version Number Guidelines:** + +- **Major (X)**: Breaking changes or major new features +- **Minor (Y)**: New features, backwards compatible +- **Patch (Z)**: Bug fixes, small improvements +- **versionCode/CURRENT_PROJECT_VERSION**: Follow the established pattern (e.g., 1000 → 1010 → 1020) + +### Step 2: Commit Version Changes + +```bash +git add package.json android/app/build.gradle ios/App/App.xcodeproj/project.pbxproj CHANGELOG.md package-lock.json +git commit -m "chore: bump app version to 0.102.0" +git push origin [your-branch] +``` + +### Step 3: Trigger Pre-release for Official QA + +1. Go to the [GitHub Actions tab](https://github.com/numbersprotocol/capture-lite/actions) +2. Find the **pre-release** workflow +3. Click "Run workflow" +4. Select the branch with your changes +5. Click "Run workflow" to trigger the build + +The GitHub Action will automatically: + +- Build the app for both iOS and Android +- Deploy to Google Play Store (alpha track for QA testing) +- Deploy to Apple TestFlight (for QA testing) + +### Step 4: Verify Deployment and Testing + +**Google Play Store (Android):** + +- Check the [Google Play Console](https://play.google.com/console) +- Verify the new version appears in the alpha track +- Test with QA team members who have access to alpha testing + +**Apple TestFlight (iOS):** + +- Check [App Store Connect](https://appstoreconnect.apple.com) +- Verify the new build appears in TestFlight +- Share with internal testers for QA validation + +### Step 5: Production Release (QA Team Action) + +Once the QA team completes testing and approves the build: + +**Google Play Store:** + +- QA team promotes the alpha version to production track directly in Play Console +- No additional developer action required + +**Apple App Store:** + +- QA team submits the TestFlight build for App Store review +- Apple reviews and releases to production +- No additional developer action required + +## Troubleshooting + +### Common Issues + +**Build Fails:** + +- Check GitHub Actions logs for detailed error messages +- Ensure all tests pass locally before triggering deployment +- Verify version numbers are properly incremented + +**Version Conflicts:** + +- Ensure versionCode in Android gradle file is always incremented +- Check that version numbers match between package.json and build.gradle + +**Deployment Not Appearing:** + +- Allow 15-30 minutes for builds to complete +- Check that you have proper access to Play Console and App Store Connect +- Verify the correct branch/tag was used for deployment + +### Getting Help + +1. Check the [GitHub Actions logs](https://github.com/numbersprotocol/capture-lite/actions) for detailed error messages +2. Contact the development team if issues persist + +## Best Practices + +- **Always test locally** before triggering QA deployment +- **Run linting** (`npm run lint`) before committing +- **Increment version numbers** for every deployment +- **Test on QA environments** before production release +- **Update CHANGELOG.md** for production releases +- **Coordinate with team** for production deployments to avoid conflicts diff --git a/README.md b/README.md index 310489194..6de27b8ac 100644 --- a/README.md +++ b/README.md @@ -5,65 +5,108 @@ | branch | build | coverage | quality | | :-----: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -| master | [![build](https://github.com/numbersprotocol/capture-lite/workflows/build/badge.svg)](https://github.com/numbersprotocol/capture-lite/actions?query=workflow%3Abuild) | [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/45ae18aaa6a7474497e0efd818452a46)](https://www.codacy.com/gh/numbersprotocol/capture-lite?utm_source=github.com&utm_medium=referral&utm_content=numbersprotocol/capture-lite&utm_campaign=Badge_Coverage) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/45ae18aaa6a7474497e0efd818452a46)](https://www.codacy.com/gh/numbersprotocol/capture-lite?utm_source=github.com&utm_medium=referral&utm_content=numbersprotocol/capture-lite&utm_campaign=Badge_Grade) | +| main | [![build](https://github.com/numbersprotocol/capture-lite/workflows/build/badge.svg)](https://github.com/numbersprotocol/capture-lite/actions?query=workflow%3Abuild) | [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/45ae18aaa6a7474497e0efd818452a46)](https://www.codacy.com/gh/numbersprotocol/capture-lite?utm_source=github.com&utm_medium=referral&utm_content=numbersprotocol/capture-lite&utm_campaign=Badge_Coverage) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/45ae18aaa6a7474497e0efd818452a46)](https://www.codacy.com/gh/numbersprotocol/capture-lite?utm_source=github.com&utm_medium=referral&utm_content=numbersprotocol/capture-lite&utm_campaign=Badge_Grade) | | develop | [![build](https://github.com/numbersprotocol/capture-lite/workflows/build/badge.svg?branch=develop)](https://github.com/numbersprotocol/capture-lite/actions?query=workflow%3Abuild) | [![Codacy Badge](https://app.codacy.com/project/badge/Coverage/45ae18aaa6a7474497e0efd818452a46?branch=develop)](https://www.codacy.com/gh/numbersprotocol/capture-lite?utm_source=github.com&utm_medium=referral&utm_content=numbersprotocol/capture-lite&utm_campaign=Badge_Coverage) | [![Codacy Badge](https://app.codacy.com/project/badge/Grade/45ae18aaa6a7474497e0efd818452a46?branch=develop)](https://www.codacy.com/gh/numbersprotocol/capture-lite?utm_source=github.com&utm_medium=referral&utm_content=numbersprotocol/capture-lite&utm_campaign=Badge_Grade) | ## Getting Started -Node 16.2.0+ and NPM 7.13.0+ is required. +### Quick Setup with AI -Install the dependencies. +For rapid development environment setup, use this prompt with Claude or other AI assistants: -```bash -npm i +``` +I need to set up the development environment for the Numbers Protocol Capture Cam mobile app from scratch. This is an Angular/Ionic mobile application with the following requirements: + +- Node.js v20.11.1+ (v20.11.1 or higher) +- NPM (comes with Node.js) +- Git for cloning the repository + +Setup steps needed: +1. Clone the repository: git clone https://github.com/numbersprotocol/capture-lite.git +2. Navigate to project directory: cd capture-lite + +**Important Note**: Some commands require environment-specific configurations and commercial package licenses that may not be available locally: + +3. Install dependencies: npm install --legacy-peer-deps + *Note: Requires commercial package authentication for some dependencies* +4. Start development server: npm run serve + *Note: Limited functionality without full environment setup* +5. Run tests: npm run test + *Note: Works with dependencies installed* +6. Run linting: npm run lint + *Note: Works with dependencies installed* + +**Alternative for environments without full setup:** +- Edit source code directly using your preferred IDE/editor +- Use GitHub Actions (Firebase Release) for testing with full dependencies +- Download builds via Firebase App Distribution for device testing + +Please help me: +1. Verify/install the correct Node.js version (v20.11.1+) +2. Clone the repository and set up code editing environment +3. Understand the codebase structure for effective development +4. Guide me through the GitHub Actions testing workflow +5. Help me with specific development tasks I want to accomplish ``` -Set the system environment variables `NUMBERS_STORAGE_BASE_URL`, `NUMBERS_STORAGE_TRUSTED_CLIENT_KEY`, `NUMBERS_BUBBLE_DB_URL`, `BUBBLE_API_URL` and `APPS_FLYER_DEV_KEY` before building the app by appending the following string in `~/.profile`: +### Manual Setup -```txt -export NUMBERS_STORAGE_BASE_URL="THE PRIVATE BASE URL" -export NUMBERS_STORAGE_TRUSTED_CLIENT_KEY="THE TRUSTED CLIENT KEY" -export NUMBERS_BUBBLE_DB_URL="THE BUBBLE DB URL" -export BUBBLE_API_URL="BUBBLE API URL" -export APPS_FLYER_DEV_KEY="APPS FLYER DEV KEY -``` +Node.js v20.11.1+ is required (v20.11.1 or higher recommended). -Preview the app in web browser. +Clone the repository: ```bash -npm run serve +git clone https://github.com/numbersprotocol/capture-lite.git +cd capture-lite ``` -## Development - -Start a local dev server for app dev/testing. +Install the dependencies: ```bash -npm run serve +npm install --legacy-peer-deps +# Note: Requires commercial package authentication ``` -Run tests. +Start the development server: ```bash -npm run test +npm run serve +# Note: Limited functionality without full environment setup ``` -Run tests in headless mode. +Run linting and tests: ```bash -npm run test.ci +npm run lint # Requires dependencies installed +npm run test # Requires dependencies installed ``` -Lint the projects. +**Alternative Development Approach:** +If dependencies can't be installed due to missing environment variables, you can still: + +- Edit source code directly using your IDE/editor +- Use GitHub Actions workflows for testing (see [Development Workflow](./DEPLOYMENT.md#development-workflow-overview)) +- Test builds via Firebase App Distribution + +## Development + +### Common Commands ```bash -npm run lint +npm run serve # Start development server +npm run test # Run unit tests +npm run test.ci # Run tests in headless mode +npm run lint # Run linting (required before commit) +npm run build # Build for production ``` -[Update `cordova-res` (splash screens and launcher icons)](https://capacitorjs.com/docs/guides/splash-screens-and-icons). +### Platform Development ```bash -cordova-res android --skip-config --copy +npm run build.android # Build and sync for Android +npm run build.ios # Build and sync for iOS +npx cap open android # Open in Android Studio +npx cap open ios # Open in Xcode ``` ### Contribution @@ -109,37 +152,25 @@ npm run build.android - This app is still in the experimental stage. - This app uses raw file system to save proofs, and thus the performance is not optimized. -### Release - -See the [Capture App release flow (Miro)](https://miro.com/app/board/o9J_knEiIYo=/?moveToWidget=3458764542656055086&cot=14). +## Development & Deployment Workflow -Some nodes below: +Due to local environment limitations, the recommended development flow uses GitHub Actions for testing: -Bump version in `package.json`. +### Development Testing -```json -{ - "version": "a.b.c" -} -``` - -Bump version in `android/app/build.gradle`. - -```gradle -android { - defaultConfig { - versionCode - versionName "a.b.c" - } -} -``` +1. **Make code changes** and ensure local build/tests pass +2. **Deploy for testing** using GitHub Actions: + - **Android APK Build**: For Android device testing + - **Firebase Release**: For distributing to test groups (Android & iOS) +3. **Test your implementation** using the deployed build +4. **Request code review** from senior developers after confirming changes work -Run `npm i` to update `package-lock.json`. +### QA/Production Deployment -Write the changelog in `CHANGELOG.md`. +After code review approval: -When push to the `master` branch with new version tag, GitHub Action would automatically do the following jobs: +1. Bump version numbers (see [DEPLOYMENT.md](./DEPLOYMENT.md)) +2. Trigger pre-release GitHub Action for Play Store (alpha) and TestFlight +3. QA team handles promotion to production -1. Create release GitHub page with debug APK. -1. Publish the app to Play Console on alpha track and Apple Store. -1. Send notification to the private `reminder-releases` slack channel. +See [DEPLOYMENT.md](./DEPLOYMENT.md) for detailed instructions. diff --git a/android/build.gradle b/android/build.gradle index 303f0ac4b..d3b45d7a9 100644 --- a/android/build.gradle +++ b/android/build.gradle @@ -7,7 +7,7 @@ buildscript { mavenCentral() } dependencies { - classpath 'com.android.tools.build:gradle:8.7.2' + classpath 'com.android.tools.build:gradle:8.9.1' classpath 'com.google.gms:google-services:4.4.2' // NOTE: Do not place your application dependencies here; they belong diff --git a/android/variables.gradle b/android/variables.gradle index 93c80a301..919ff53ef 100644 --- a/android/variables.gradle +++ b/android/variables.gradle @@ -1,7 +1,7 @@ ext { minSdkVersion = 28 - compileSdkVersion = 35 - targetSdkVersion = 35 + compileSdkVersion = 36 + targetSdkVersion = 36 androidxActivityVersion = '1.9.2' androidxAppCompatVersion = '1.7.0' androidxCoordinatorLayoutVersion = '1.2.0'