Merge pull request #3343 from numbersprotocol/docs-improve-development-documentation

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

Author: olgahaha

.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

.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:

.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'

.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

.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 }}
-            <https://github.com/numbersprotocol/capture-lite/releases/tag/${{ steps.version_check.outputs.version }}|GitHub Release Note>
-
-            APKs
-
-            - <https://drive.google.com/drive/folders/1NH-4mruBBubxHMfXF6VXaKRCQ76Ldg_n?usp=sharing|Google Drive>
-            - <https://play.google.com/apps/testing/io.numbersprotocol.capturelite|Google Play Closed Alpha Testing (release)>
-
-            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