# Installation Guide

This guide will walk you through setting up NQ on your computer, step-by-step. Even if you're not a developer, you can follow these instructions to get NQ running.

**Time needed:** 30 minutes to 2 hours (depending on experience level)

**What you'll do:**
1. Install required software (Go, Node.js, and a database)
2. Download NQ
3. Set up the backend (the "brain" of NQ)
4. Set up the frontend (the mobile app)
5. Start using NQ!

## Step 1: Install Required Software

Before NQ can run, you need to install three programs. Don't worry - they're all free!

### Install Go (Programming Language)

Go powers NQ's backend server.

**What to do:**
1. Visit [https://go.dev/dl/](https://go.dev/dl/)
2. Download the installer for your operating system:
   - Windows: Download the `.msi` file
   - Mac: Download the `.pkg` file
   - Linux: Download the appropriate tarball
3. Run the installer and follow the on-screen instructions
4. Accept the default installation options

**Verify it worked:**
- Open Terminal (Mac/Linux) or Command Prompt (Windows)
- Type: `go version`
- You should see something like: `go version go1.25.1`

### Install Node.js (JavaScript Runtime)

Node.js runs the mobile app development server.

**What to do:**
1. Visit [https://nodejs.org/](https://nodejs.org/)
2. Download the **LTS** (Long Term Support) version - this is the recommended, stable version
3. Run the installer
4. Follow the installation wizard (accept default options)

**Verify it worked:**
- Open Terminal/Command Prompt
- Type: `node --version`
- You should see a version number like: `v18.x.x` or higher

### Set Up Neo4j Database

Neo4j is a special type of database that stores connections between your media (like "this movie is similar to that one").

**Choose one option:**

#### Option A: Neo4j Aura (Cloud) - **Recommended for beginners**

This is easier because nothing installs on your computer.

**What to do:**
1. Go to [https://neo4j.com/cloud/aura/](https://neo4j.com/cloud/aura/)
2. Click "Start Free"
3. Create an account (or sign in with Google)
4. Click "Create Instance" → Select "Free" tier
5. **IMPORTANT**: Save the credentials shown! You'll need:
   - Connection URI (looks like: `neo4j+s://xxxxx.databases.neo4j.io`)
   - Username (usually `neo4j`)
   - Password (auto-generated)
6. Click "Download and Continue" to save these to a text file
7. Wait 1-2 minutes for your database to start

#### Option B: Neo4j Desktop (Local) - **For advanced users**

Install the database on your computer.

**What to do:**
1. Go to [https://neo4j.com/download/](https://neo4j.com/download/)
2. Download Neo4j Desktop for your operating system
3. Install and open Neo4j Desktop
4. Create a new project (name it "NQ")
5. Add a new "Local DBMS" (database)
6. Set a password you'll remember
7. Click "Start" to run your database
8. Your credentials are:
   - Connection URI: `bolt://localhost:7687`
   - Username: `neo4j`
   - Password: [your chosen password]

## Step 2: Clone NQ

```bash
git clone https://github.com/grillinr/nq.git

cd nq
```

## Step 3: Set Up the Backend

### 3.1: Navigate to the Backend Folder

```bash
cd backend
```

### 3.2: Create Your Configuration File

**Mac/Linux:**
```bash
cp .envtemplate .env
```

**Windows:**
```cmd
copy .envtemplate .env
```

### 3.3: Add Your Database Credentials

**What to do:**
1. Open the `.env` file
2. Find these lines:
   ```bash
   NEO4J_URI=
   NEO4J_USERNAME=
   NEO4J_PASSWORD=
   NEO4J_DATABASE=
   ```
3. Fill in your Neo4j credentials from Step 1:
   ```bash
   NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io  # Your connection URI from Aura
   NEO4J_USERNAME=neo4j                           # Usually just "neo4j"
   NEO4J_PASSWORD=YourPasswordHere                # The password you saved
   NEO4J_DATABASE=neo4j                          # Usually just "neo4j"
   ```
4. Save the file

### 3.4: Test the Backend

```bash
go run .
```

**If you see errors:**
- "Failed to connect to Neo4j" → Check your credentials in `.env`
- "Port 8080 already in use" → Close other programs using that port

### 3.5: Verify It's Working

While the backend is running:
1. Open a web browser
2. Go to: `http://localhost:8080`
3. You should see a page called "GraphQL Playground"

## Step 4: Set Up the Frontend

### 4.1: Navigate to the Frontend Folder

Open a **new** terminal window:

```bash
cd nq-frontend
```

### 4.2: Install Dependencies

```bash
npm install
```

### 4.3: Start the Development Server

```bash
npx expo start
```

### 4.4: Open the App

**Option A: On Your Phone (Easiest)**
1. Install the "Expo Go" app from your phone's app store (it's free)
2. Open Expo Go
3. Scan the QR code shown in your terminal
4. Wait for the app to load (first time takes a minute)

**Option B: Android Emulator**
1. Install [Android Studio](https://developer.android.com/studio)
2. Set up an Android Virtual Device (AVD) - see [Android setup guide](https://docs.expo.dev/workflow/android-studio-emulator/)
3. Start the emulator
4. In the Expo terminal, press `a`

**Option C: iOS Simulator (Mac only)**
1. Install Xcode from the Mac App Store
2. In the Expo terminal, press `i`
3. The simulator will open and load the app

**Option D: Web Browser (Limited)**
1. In the Expo terminal, press `w`
2. A browser window opens (note: some features won't work in browser)

## Step 5: Verify Everything Works

### Test the Full System

To use NQ, you need **both** running at the same time:
- **Terminal 1**: Backend (`cd backend && go run .`)
- **Terminal 2**: Frontend (`cd nq-frontend && npx expo start`)

Keep both terminal windows open while using NQ.

## Next Steps

1. **Connect Your Services**
   - See the [API Data Sources](API-Data-Sources.md) guide
   - Get API keys for services you want to use
   - Add them to your `.env` file

2. **Learn to Use NQ**
   - Read the [User Guide](User-Guide.md) for detailed instructions
   - Start syncing your media libraries
   - Get personalized recommendations!

3. **Explore the Features**
   - Try the GraphQL Playground at `http://localhost:8080`
   - Browse your media library in the app
   - Discover new content based on your preferences