Skip to content

Commit 4d16e57

Browse files
Manuel RuckManAnRuck
Manuel Ruck
authored and
ManAnRuck
committed
feat: add testing and deployment documentation for iOS and Android
1 parent 84e9030 commit 4d16e57

File tree

5 files changed

+447
-0
lines changed

5 files changed

+447
-0
lines changed

‎README.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# DEMOCRACY Client
2+
3+
A mobile application that brings the German Bundestag to citizens' smartphones, allowing them to vote on parliamentary procedures and compare their choices with official results.
4+
5+
## Features
6+
7+
- Browse and search official German Bundestag procedures
8+
- Vote on procedures as if you were a member of parliament
9+
- Compare your voting behavior with the community and the Bundestag
10+
- Analyze your agreement with different parties and candidates
11+
- Receive notifications about important parliamentary activities
12+
13+
## Technology Stack
14+
15+
- React Native with Expo Router
16+
- Apollo GraphQL client
17+
- Styled Components
18+
- TypeScript
19+
- Recoil and Zustand for state management
20+
- E2E testing with Maestro
21+
- CI/CD with GitHub Actions
22+
23+
## Getting Started
24+
25+
### Prerequisites
26+
27+
- Node.js
28+
- Yarn package manager (v1.22.19+)
29+
- iOS development environment (for iOS)
30+
- Xcode
31+
- CocoaPods
32+
- Android development environment (for Android)
33+
- Android Studio
34+
- Android SDK
35+
36+
### Installation
37+
38+
1. Clone the repository:
39+
40+
```bash
41+
git clone https://github.com/democracy-deutschland/democracy-client.git
42+
cd democracy-client
43+
```
44+
45+
2. Install dependencies:
46+
47+
```bash
48+
yarn install
49+
```
50+
51+
3. Generate GraphQL types:
52+
53+
```bash
54+
yarn codegen
55+
```
56+
57+
4. Start the development server:
58+
59+
```bash
60+
yarn start
61+
```
62+
63+
5. Run on specific platforms:
64+
```bash
65+
yarn ios # Run on iOS simulator
66+
yarn android # Run on Android emulator
67+
```
68+
69+
## Development
70+
71+
- Run type checking: `yarn lint:ts`
72+
- Run linter: `yarn lint`
73+
- Run doctor for Expo issues: `yarn doctor`
74+
75+
## Testing
76+
77+
The project uses Maestro for end-to-end testing. See [Testing Documentation](./docs/TESTING.md) for more information.
78+
79+
Run tests with:
80+
81+
```bash
82+
yarn test:e2e # Run all E2E tests
83+
yarn test:e2e:smoke # Run smoke tests only
84+
yarn test:e2e:verification # Run verification flow tests only
85+
```
86+
87+
## Deployment
88+
89+
This project uses fastlane for both iOS and Android deployments.
90+
91+
- For iOS deployment details, see [iOS Deployment](./docs/deployment/IOS.md)
92+
- For Android deployment details, see [Android Deployment](./docs/deployment/ANDROID.md)
93+
94+
## Project Structure
95+
96+
- `src/`
97+
- `app/` - Expo Router app directory
98+
- `components/` - Reusable components
99+
- `screens/` - Screen components
100+
- `api/` - API and state management
101+
- `__generated__/` - Generated GraphQL types
102+
- `hooks/` - Custom React hooks
103+
- `lib/` - Utility functions
104+
- `data/` - Static data files
105+
- `types/` - Type definitions
106+
- `styles/` - Theme and styling configurations
107+
- `.github/` - GitHub workflows and CI configuration
108+
- `.maestro/` - E2E tests
109+
- `deploy/` - Deployment configurations
110+
- `android/` - Android deployment settings and fastlane setup
111+
- `ios/` - iOS deployment settings and fastlane setup
112+
- `assets/` - Static assets
113+
114+
## Architecture
115+
116+
For a detailed explanation of the application architecture, see [Architecture Documentation](./docs/ARCHITECTURE.md).
117+
118+
## License
119+
120+
Apache License 2.0
121+
122+
## Contact
123+
124+
[democracy-deutschland.de](https://democracy-deutschland.de)
125+
[[email protected]](mailto:[email protected])

‎docs/ARCHITECTURE.md‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
# Application Architecture
2+
3+
This document provides an overview of the DEMOCRACY client application architecture.
4+
5+
## Overview
6+
7+
The DEMOCRACY client is a cross-platform mobile application built with React Native and Expo. The app follows a component-based architecture with a focus on maintainability, performance, and user experience.
8+
9+
## Technology Stack
10+
11+
- **React Native**: Core framework for building the mobile app
12+
- **Expo**: Development platform for React Native
13+
- **Expo Router**: File-based routing system for navigation
14+
- **Apollo Client**: GraphQL client for data fetching and state management
15+
- **Recoil & Zustand**: State management solutions
16+
- **TypeScript**: Static type checking
17+
- **Styled Components**: Component styling
18+
- **GraphQL**: API communication protocol
19+
20+
## Project Structure
21+
22+
```
23+
src/
24+
├── __generated__/ # Auto-generated TypeScript types for GraphQL
25+
├── api/ # API and state management
26+
│ ├── apollo/ # Apollo Client setup
27+
│ ├── hooks/ # API-related hooks
28+
│ └── state/ # State management
29+
├── app/ # Expo Router app directory
30+
├── components/ # Reusable UI components
31+
├── data/ # Static data files
32+
├── hooks/ # Custom React hooks
33+
├── lib/ # Utility functions
34+
├── screens/ # Screen components
35+
├── styles/ # Theme and styling
36+
└── types/ # Type definitions
37+
```
38+
39+
## Key Architecture Concepts
40+
41+
### Navigation
42+
43+
The application uses Expo Router for navigation, which provides a file-based routing system. The navigation structure is defined in the `src/app` directory, with each file representing a route.
44+
45+
### Data Flow
46+
47+
1. **GraphQL Operations**: Defined in component files or dedicated query files
48+
2. **Apollo Client**: Executes GraphQL operations against the backend
49+
3. **Component Consumption**: Components use Apollo hooks (useQuery, useMutation) to access data
50+
4. **Local State**: Managed through Apollo Client cache, Recoil, or Zustand
51+
52+
### Component Architecture
53+
54+
Components follow a hierarchical structure:
55+
56+
- **Screen Components**: Top-level components representing entire screens
57+
- **Feature Components**: Components that implement specific features
58+
- **UI Components**: Reusable UI elements like buttons, inputs, etc.
59+
60+
### State Management
61+
62+
The application uses a combination of state management solutions:
63+
64+
- **Apollo Client Cache**: For GraphQL data
65+
- **Recoil**: For shared application state
66+
- **Zustand**: For specific feature state
67+
- **React Context**: For theme, authentication, and other app-wide concerns
68+
69+
### Authentication Flow
70+
71+
1. User enters credentials or verifies phone number
72+
2. Authentication token is stored securely using react-native-keychain
73+
3. Token is attached to GraphQL requests using Apollo Link Context
74+
4. Protected routes check for valid authentication
75+
76+
## App Variants
77+
78+
The application supports different build variants:
79+
80+
- **Production**: Regular user-facing app
81+
- **Internal**: Used for development and testing
82+
83+
These variants are configured through environment variables and the app.config.ts file.
84+
85+
## Testing Strategy
86+
87+
- **End-to-End Testing**: Using Maestro for testing complete user flows
88+
- **Type Checking**: TypeScript for static analysis
89+
90+
## Performance Considerations
91+
92+
- Apollo Client cache configuration for optimized data fetching
93+
- React memo and useMemo for component optimization
94+
- Proper handling of large lists and data sets

‎docs/TESTING.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
# Testing Documentation
2+
3+
This document covers the testing approach and methodologies used in the DEMOCRACY client application.
4+
5+
## E2E Testing with Maestro
6+
7+
End-to-end tests are implemented using Maestro, a mobile UI testing framework.
8+
9+
### Setup
10+
11+
1. Install Maestro:
12+
```bash
13+
curl -Ls "https://get.maestro.mobile.dev" | bash
14+
```
15+
16+
2. Make sure you have either:
17+
- An iOS Simulator running (for iOS tests)
18+
- An Android Emulator running (for Android tests)
19+
20+
### Running Tests
21+
22+
Run all tests:
23+
```bash
24+
yarn test:e2e
25+
```
26+
27+
Run specific test flows:
28+
```bash
29+
yarn test:e2e:smoke # Run smoke tests
30+
yarn test:e2e:verification # Run verification flow tests
31+
```
32+
33+
### Test Flows
34+
35+
- `smoke.yaml`: Basic app launch and navigation tests
36+
- `verification.yaml`: Tests the phone verification flow
37+
38+
### Test Structure
39+
40+
Tests are located in the `.maestro/flows/` directory and are organized by feature or flow. Each test file is a YAML configuration defining the test steps and assertions.
41+
42+
### Writing Tests
43+
44+
When writing new tests:
45+
1. Create a new `.yaml` file in the `.maestro/flows/` directory
46+
2. Define test steps using Maestro's YAML syntax
47+
3. Add appropriate assertions to verify the functionality
48+
4. Add a script to `package.json` to run your specific test
49+
50+
## CI/CD Integration
51+
52+
E2E tests are integrated into the GitHub Actions workflow to ensure automated testing on each pull request and deploy.

‎docs/deployment/ANDROID.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
# Android Deployment
2+
3+
This guide outlines the process of building and deploying the Android app to the Google Play Store.
4+
5+
## Prerequisites
6+
7+
- Java Development Kit (JDK)
8+
- Android SDK
9+
- Access to the Google Play Console
10+
- Ruby environment for fastlane
11+
12+
## Setup
13+
14+
1. Install the required Ruby gems:
15+
16+
```bash
17+
cd deploy/android
18+
bundle install
19+
```
20+
21+
2. Configure environment variables:
22+
- Ensure the keystore file and credentials are properly set up
23+
- Set up Google Play API access
24+
25+
## Signing Configuration
26+
27+
The app is signed using a keystore file. The signing configuration is defined in the Fastfile.
28+
29+
To access the keystore:
30+
```bash
31+
# Decrypt the keystore file if encrypted
32+
gpg --decrypt deploy/android/democracy2-release-key.keystore.gpg > android/app/democracy2-release-key.keystore
33+
```
34+
35+
## Build and Deploy Process
36+
37+
### Internal Testing Track
38+
39+
To build and deploy to the internal testing track:
40+
41+
```bash
42+
cd deploy/android
43+
bundle exec fastlane android internal
44+
```
45+
46+
This will:
47+
1. Increment the version code
48+
2. Build the Android app
49+
3. Sign the APK/AAB
50+
4. Upload to the internal testing track
51+
52+
### Production Release
53+
54+
To release to production:
55+
56+
1. Verify the app in the internal testing track
57+
2. Update the release notes in `deploy/android/fastlane/metadata`
58+
3. Deploy to production:
59+
```bash
60+
cd deploy/android
61+
bundle exec fastlane android production
62+
```
63+
64+
### Beta Track
65+
66+
To release to the beta track:
67+
68+
```bash
69+
cd deploy/android
70+
bundle exec fastlane android beta
71+
```
72+
73+
## CI/CD Integration
74+
75+
The fastlane setup is integrated with GitHub Actions for automated builds and deployments. See the `.github/workflows` directory for the workflow configurations.
76+
77+
## Troubleshooting
78+
79+
### Common Issues
80+
81+
- **Signing Issues**: Verify that the keystore file is accessible and the password is correct
82+
- **Google Play API Errors**: Check that the service account has the proper permissions
83+
- **Build Errors**: Confirm that all dependencies are properly resolved
84+
85+
### Logs
86+
87+
Fastlane logs are stored in:
88+
- The terminal output when running locally
89+
- GitHub Actions logs when running in CI/CD

0 commit comments

Comments
 (0)