ACEquity-wma/README.md

# ACEquity - Stock Market Aggregator (WebView Mobile App)

ACEquity is a lightweight React Native CLI application that wraps the ACE Stock Market Aggregator website in a WebView to provide a native mobile experience. The mobile app is a thin wrapper around the aggregator site, focused on browsing market data, watchlists, and alerts rather than local media downloads.

## Prerequisites

- **Node.js** >= 18
- **JDK** 17 (recommended for React Native)
- **Android Studio** with:
  - Android SDK
  - Android SDK Platform-Tools
  - Android Emulator (optional)
- **Watchman** (recommended for macOS)

## Environment Setup

### 1. Install Homebrew Dependencies (macOS)

```bash
brew install node watchman
brew install --cask zulu@17  # OpenJDK 17
```

### 2. Set Environment Variables

Add to your `~/.zshrc` or `~/.bash_profile`:

```bash
# Java Home (Zulu JDK 17)
export JAVA_HOME=/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home

# Android SDK
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/platform-tools
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/tools/bin
```

Then reload:
```bash
source ~/.zshrc
```

### 3. Verify Setup

```bash
# Check Java version (should be 17.x)
java -version

# Check Android SDK
echo $ANDROID_HOME
adb --version
```

## Installation

```bash
# Install dependencies
npm install

# iOS only: Install CocoaPods (if building for iOS later)
# cd ios && pod install && cd ..
```

## Running the App

### Quick Start with Emulator (Recommended for Development)

**First time? Start here:**

1. **Create an Android Virtual Device (AVD):**
   - Open Android Studio → Device Manager → Create Device
   - Select Pixel 5 → API 34 → Name it `Pixel_5_API_34`
   - See [ANDROID_EMULATOR_SETUP.md](ANDROID_EMULATOR_SETUP.md) for details

2. **Use the helper script:**
   ```bash
   ./dev-helper.sh
   ```
   This interactive script will guide you through starting the emulator and app.

**Or manually:**

```bash
# Terminal 1: Start Metro bundler
npm start

# Terminal 2: Start emulator
npm run emulator:start

# Terminal 3: Build and run app
npm run android:emulator
```

For complete emulator setup and troubleshooting, see [RUNNING_ON_EMULATOR.md](RUNNING_ON_EMULATOR.md).

### Run on Physical Android Device

1. Enable USB debugging on your device
2. Connect via USB
3. Verify connection: `adb devices`
4. Run:
   ```bash
   npm start  # Terminal 1
   npm run android:device  # Terminal 2
   ```

### Available Scripts

```bash
npm start                # Start Metro bundler
npm run android          # Run on any connected device/emulator
npm run android:emulator # Run specifically on emulator
npm run android:device   # Run specifically on physical device
npm run emulator:list    # List available AVDs
npm run emulator:start   # Start emulator
npm run emulator:check   # Check connected devices
npm run clean            # Clean build
npm run start:reset      # Start with cleared cache
```

### Build Debug APK

```bash
cd android
./gradlew assembleDebug
```

The APK will be at: `android/app/build/outputs/apk/debug/app-debug.apk`

### Install APK via ADB

```bash
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
```

## Project Structure

```
ACEquity/
├── App.tsx                 # Main WebView component
├── android/
│   ├── app/
│   │   └── src/main/
│   │       └── AndroidManifest.xml  # Permissions config
│   ├── gradle.properties   # Gradle settings
│   └── local.properties    # SDK path (git-ignored)
├── package.json
└── README.md
```

## Configuration

### Change Target URL

By default the app points to the ACE Stock Market Aggregator:

```typescript
const TARGET_URL = 'https://ace.webark.in';
```

To point the app at a different site (e.g., staging or a custom aggregator), update the `TARGET_URL` constant in `App.tsx`.

### Permissions

The AndroidManifest.xml includes:
- `INTERNET` - Required for WebView access
- `ACCESS_NETWORK_STATE` - For connectivity checks

If you add native features (push notifications, local caching, downloads, etc.), add the appropriate permissions and update `AndroidManifest.xml` accordingly.

## Troubleshooting

See the Troubleshooting section in the setup guide or check:
- [React Native Environment Setup](https://reactnative.dev/docs/environment-setup)
- [React Native WebView Docs](https://github.com/react-native-webview/react-native-webview)

## Future Features

- [ ] Push notifications for price alerts and market news
- [ ] Watchlist sync and account/login support
- [ ] Offline caching of key market pages/charts for faster access
- [ ] Deep links to specific stocks, charts and shared links
- [ ] Native UI components for quick actions and price alerts

## License

MIT