Skip to content

docs: add SETUP.md for contributor onboarding (Windows, Android, common issues) #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SISIR-REDDY wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add SETUP.md for contributor onboarding (Windows, Android, common issues) #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,21 +14,23 @@ DocPilot is a Flutter application designed to assist healthcare providers in rec

## Getting Started

> For a detailed, step-by-step setup guide (including Windows, Android Studio, AVD, and common issues) see [SETUP.md](SETUP.md).

### Prerequisites

- Flutter SDK (latest version recommended)
- Dart SDK
- Android Studio / VS Code with Flutter extensions
- Flutter SDK 3.27+ (stable channel)
- Dart SDK 3.6+
- Android Studio (Hedgehog or newer) — needed for Android SDK and emulator
- API keys for:
- Deepgram (for speech-to-text)
- Google Gemini (for AI processing)
- [Deepgram](https://console.deepgram.com) (speech-to-text)
- [Google Gemini](https://aistudio.google.com/app/apikey) (AI processing)

### Installation

1. Clone the repository:
```bash
git clone https://github.com/yourusername/docpilot.git
cd docpilot
git clone https://github.com/AOSSIE-Org/DocPilot.git
cd DocPilot
```

2. Install dependencies:
Expand Down
217 changes: 217 additions & 0 deletions SETUP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
# DocPilot — Contributor Setup Guide

This guide covers everything needed to get DocPilot running locally for development and testing. It includes extra detail for contributors on **Windows** and for **Android** device/emulator testing, where the setup has a few more steps than on macOS/Linux.

---

## Table of Contents

1. [Prerequisites](#prerequisites)
2. [Flutter SDK Installation](#flutter-sdk-installation)
3. [Android Studio and SDK Setup](#android-studio-and-sdk-setup)
4. [Project Setup](#project-setup)
5. [API Keys](#api-keys)
6. [Running the App](#running-the-app)
7. [Common Issues](#common-issues)

---

## Prerequisites

| Tool | Minimum version | Notes |
|---|---|---|
| Flutter | 3.27.x (stable) | Check with `flutter --version` |
| Dart | 3.6.x | Included with Flutter |
| Android Studio | Hedgehog (2023.1) or newer | For Android SDK and AVD |
| Git | Any recent version | |
| VS Code (optional) | Any | With the Flutter + Dart extensions |

---

## Flutter SDK Installation

### Windows

1. Download the Flutter SDK zip from https://docs.flutter.dev/get-started/install/windows
2. Extract it to a path **without spaces**, e.g. `C:\dev\flutter`
3. Add `C:\dev\flutter\bin` to your `PATH` environment variable:
- Open **System Properties** → **Environment Variables**
- Edit the `Path` variable under **User variables**
- Add the `bin` path and click OK
4. Open a **new** terminal and verify:
```
flutter --version
flutter doctor
```
Comment on lines +42 to +45
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add fenced code block language for command snippet.

This block should be tagged (e.g., bash) to satisfy markdownlint MD040.

Suggested fix 
-   ```
+   ```bash
    flutter --version
    flutter doctor
    ```
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
```
flutter --version
flutter doctor
```
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 42-42: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@SETUP.md` around lines 42 - 45, The fenced code block containing the commands
"flutter --version" and "flutter doctor" lacks a language tag; update the
opening fence from ``` to ```bash so the block is tagged as bash (ensuring
markdownlint MD040 compliance) near the code snippet in SETUP.md.


### macOS / Linux

Use the official installer or `fvm` (Flutter Version Manager):
```bash
# macOS via Homebrew
brew install --cask flutter

# or via fvm
dart pub global activate fvm
fvm install stable
fvm use stable
```

Make sure to use the **stable** channel:
```bash
flutter channel stable
flutter upgrade
```

---

## Android Studio and SDK Setup

Even if you use VS Code as your editor, Android Studio is still needed to manage the Android SDK and create emulators.

1. Download and install Android Studio from https://developer.android.com/studio
2. On first launch, go through the **Setup Wizard** — it installs the default Android SDK
3. Open **SDK Manager** (Tools → SDK Manager):
- Under **SDK Platforms**: install **Android 14 (API 34)** or newer
- Under **SDK Tools**: make sure these are checked:
- Android SDK Build-Tools
- Android Emulator
- Android SDK Platform-Tools
- Intel HAXM *(Windows only — required for emulator acceleration)*
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🌐 Web query:

Is Intel HAXM still required for Android Emulator acceleration on Windows in current Android Studio versions, or should docs recommend WHPX/Android Emulator Hypervisor Driver instead?

💡 Result:

Intel HAXM is no longer required (and, for current Emulator versions, no longer usable) for Android Emulator acceleration on Windows.

  • Google’s official acceleration docs state that starting with Android Emulator 36.2.x.x, the emulator won’t use HAXM anymore, and they recommend Windows Hypervisor Platform (WHPX) instead. They also describe Android Emulator Hypervisor Driver (AEHD) as an alternative hypervisor on Windows (with a stated sunset date of Dec 31, 2026, after which users should transition to WHPX). [1]
  • The official Emulator release notes for 36.2.11 (Oct 9, 2025) explicitly say “HAXM support is removed from the Emulator” and that users will be prompted to install AEHD if they try to use HAXM. [2]

So yes: current docs should recommend WHPX first, and mention AEHD as an alternative (not HAXM), with the caveat that AEHD is planned to be sunset at the end of 2026. [1]

Sources: [1] [2]

Replace outdated Intel HAXM requirement with current Windows hypervisor guidance.

Intel HAXM is no longer supported on Windows—as of Android Emulator 36.2.x.x (released Oct 2025), HAXM support has been removed and the emulator will no longer use it. Line 80 should instead recommend Windows Hypervisor Platform (WHPX) as the primary acceleration method, with Android Emulator Hypervisor Driver (AEHD) as an alternative (sunset scheduled for Dec 31, 2026).

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@SETUP.md` at line 80, Replace the outdated bullet "Intel HAXM *(Windows only
— required for emulator acceleration)*" with guidance that recommends Windows
Hypervisor Platform (WHPX) as the primary emulator acceleration method on
Windows and lists Android Emulator Hypervisor Driver (AEHD) as an alternative
(note AEHD sunset scheduled for Dec 31, 2026); update the phrasing around the
original "Intel HAXM" text so it explicitly states HAXM is no longer supported
by modern Android Emulator releases (e.g., 36.2.x.x) and provide brief
actionable instructions to enable WHPX (and mention AEHD as fallback).

4. Accept all SDK licenses by running:
```bash
flutter doctor --android-licenses
```
Type `y` at each prompt.
5. Run `flutter doctor` again — the Android toolchain check should now pass.

### Creating a Virtual Device (Emulator)

For testing DocPilot's microphone features, a **physical Android device is strongly recommended** because microphone passthrough does not work reliably in most emulators.

To create an emulator anyway:
1. Open **Device Manager** in Android Studio (Tools → Device Manager)
2. Click **Create Virtual Device**
3. Choose a Pixel device (e.g. Pixel 6), click **Next**
4. Select a system image (API 34 recommended), download it if needed
5. Finish the wizard and start the emulator

> **Note for emulator users:** The `record` package used by DocPilot accesses the real microphone. Audio recording will not work inside an emulator unless you enable microphone passthrough in your hypervisor settings. Use a real device for end-to-end testing.

### Connecting a Physical Device (Windows)

1. Enable **Developer Options** on your phone: go to Settings → About → tap **Build Number** 7 times
2. Enable **USB Debugging** inside Developer Options
3. Connect via USB and accept the debugging prompt on the phone
4. Verify Flutter can see the device:
```bash
flutter devices
```

---

## Project Setup

```bash
git clone https://github.com/AOSSIE-Org/DocPilot.git
cd DocPilot
flutter pub get
```

---

## API Keys

DocPilot requires two API keys. Copy the example env file and fill in your keys:

```bash
cp .env.example .env
```

Open `.env` and replace the placeholders:

```
GEMINI_API_KEY=your_gemini_api_key_here
DEEPGRAM_API_KEY=your_deepgram_api_key_here
```
Comment on lines +133 to +136
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add fenced code block language for .env example.

This block should declare a language (e.g., dotenv or bash) for markdownlint compliance.

Suggested fix 
-```
+```dotenv
 GEMINI_API_KEY=your_gemini_api_key_here
 DEEPGRAM_API_KEY=your_deepgram_api_key_here
</details>

<!-- suggestion_start -->

<details>
<summary>📝 Committable suggestion</summary>

> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.21.0)

[warning] 133-133: Fenced code blocks should have a language specified

(MD040, fenced-code-language)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@SETUP.md` around lines 133 - 136, The fenced code block showing environment
variable examples in SETUP.md lacks a language specifier; update the opening
fence to include a language (e.g., change "```" to "```dotenv" or "```bash") so
markdownlint passes and syntax highlighting works for the
GEMINI_API_KEY/DEEPGRAM_API_KEY example.


**Getting a Deepgram key:**
1. Sign up at https://console.deepgram.com
2. Go to **API Keys** → **Create a new API key**
3. Copy the key into `.env`

**Getting a Gemini key:**
1. Go to https://aistudio.google.com/app/apikey
2. Click **Create API key**
3. Copy the key into `.env`

> **Important:** Never commit your `.env` file. It is listed in `.gitignore`. Only `.env.example` (with placeholder values) is tracked by git.

---

## Running the App

```bash
# List available devices
flutter devices

# Run on a connected Android device
flutter run

# Run on a specific device by ID
flutter run -d <device-id>

# Run in release mode (closer to production performance)
flutter run --release
```

To run the tests:
```bash
flutter test
```

To check for lint issues:
```bash
flutter analyze
```

---

## Common Issues

### `flutter doctor` shows Android SDK not found (Windows)
- Open Android Studio → Tools → SDK Manager and note the **Android SDK Location** path
- Run: `flutter config --android-sdk "C:\path\to\your\sdk"`

### `Unable to locate adb` or device not detected
- Make sure **Platform-Tools** is installed via SDK Manager
- Add `%LOCALAPPDATA%\Android\Sdk\platform-tools` to your `PATH` (Windows)
- Try unplugging and replugging the USB cable, and re-accepting the debug prompt

### `MissingPluginException` for microphone/record on first run
```bash
flutter clean
flutter pub get
flutter run
```

### API key errors at runtime
- Make sure `.env` exists at the project root (not inside `lib/`)
- Make sure the values are real keys, not the placeholder text from `.env.example`
- The app will show an inline banner on the main screen if it detects missing or placeholder keys

### `flutter pub get` fails behind a corporate proxy (Windows)
```bash
set FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn
set PUB_HOSTED_URL=https://pub.flutter-io.cn
flutter pub get
```

### Gradle build fails with `Could not find` errors
```bash
cd android
./gradlew clean # macOS/Linux
gradlew.bat clean # Windows
cd ..
flutter run
```