Skip to content

setup.md

Latest commit

 

History

History
225 lines (159 loc) · 7.09 KB

setup.md

File metadata and controls

225 lines (159 loc) · 7.09 KB
Raw

AxeP Setup & Run Guide

AxeP is composed of four main layers. You need to run them in the following order to ensure they connect properly.

0. Prerequisites

  • Docker (for PostgreSQL and Redis)
  • Node.js & npm (v20+)
  • Python 3.12+
  • Go 1.22+
  • Flutter SDK ^3.7.2 (for mobile app)
  • Android Studio (for Android SDK & emulator)
  • A physical Android device (recommended) or Android emulator (API 26+)

1. Database & Cache (Docker)

The backend expects PostgreSQL on port 5432 and Redis on port 6379.

# From the root directory, start the containers in the background:
docker compose up -d

2. Python Backend (FastAPI)

This handles the main API, WebSockets, and Gemini native LLM generation. It connects to Postgres and Redis.

cd server
# If you don't have a virtual environment yet:
# python -m venv .venv
# source .venv/bin/activate
# pip install -r requirements.txt

# Run the server on port 8000:
uvicorn app.main:app --reload --port 8000

(Leave this terminal running)

3. Go AI Engine (Optional but recommended)

This engine calculates deeper analytics, ARoI, Burnout profiles, and manages the local SQLite database (ai_engine.db).

cd ai-engine
# Run the Go server on port 8083:
go run ./cmd/server

(Leave this terminal running)

4. Frontend (Next.js)

The React dashboard where you interact with the app.

cd web
# Install dependencies if you haven't:
# npm install

# Run the development server on port 3000:
npm run dev

(Leave this terminal running)

5. Desktop Daemon (Telemetry)

The Go daemon that tracks your keyboard events, active window switches, and calculates your Cognitive Liquidity (CL) locally.

cd daemon/src
# Run the daemon securely (requires root access for evdev/input listening on Linux)
# Make sure your backend username/password match what you registered on the frontend!
sudo go run . --debug --user YOUR_USERNAME --pass YOUR_PASSWORD

(Leave this terminal running)

6. Mobile App — AxeP for Android (Flutter + Kotlin)

The companion Android app provides on-device focus tracking, CL computation, LLM-powered quizzes, and QR-based laptop pairing.

6a. Install Flutter SDK

  1. Download Flutter SDK from flutter.dev/docs/get-started/install
  2. Extract to a permanent location (e.g. C:\flutter on Windows, ~/flutter on macOS/Linux)
  3. Add Flutter's bin/ directory to your system PATH:
    • Windows: Add C:\flutter\bin to your PATH environment variable
    • macOS/Linux: Add export PATH="$HOME/flutter/bin:$PATH" to your shell profile (.bashrc, .zshrc, etc.)
  4. Verify the installation:
flutter --version
# Should show Flutter 3.7.2 or higher

6b. Install Android Studio & Android SDK

  1. Download Android Studio from developer.android.com/studio
  2. Run the installer and complete the setup wizard
  3. During setup, ensure the following are installed:
    • Android SDK (API 35 — required by the app's compileSdk)
    • Android SDK Command-line Tools
    • Android SDK Build-Tools
    • Android SDK Platform-Tools
    • NDK (version 27.0.12077973 — used by the app)
  4. Open Android Studio → Settings → Languages & Frameworks → Android SDK and note the SDK path
  5. Set the ANDROID_HOME environment variable:
    • Windows: C:\Users\<you>\AppData\Local\Android\Sdk
    • macOS: ~/Library/Android/sdk
    • Linux: ~/Android/Sdk

6c. Configure Flutter for Android

# Point Flutter to your Android SDK
flutter config --android-sdk <your-android-sdk-path>

# Accept all Android licenses
flutter doctor --android-licenses

# Run Flutter doctor to verify everything is green
flutter doctor

Ensure the output shows checkmarks for:

  • ✅ Flutter
  • ✅ Android toolchain
  • ✅ Connected device (if a phone is plugged in)

6d. Set Up a Physical Device (Recommended)

A physical Android phone is strongly recommended because the app uses:

  • AccessibilityService (for typing heuristics + screen text extraction)
  • UsageStatsManager (for app switch tracking)
  • Camera (for QR scanning)

These features don't work well or at all in emulators.

  1. On your phone, enable Developer Options (tap Build Number 7 times in Settings → About Phone)
  2. Enable USB Debugging in Developer Options
  3. Connect via USB and accept the debugging prompt on the phone
  4. Verify:
flutter devices
# Should list your phone

6e. Install Dependencies & Run

cd axep

# Get all Flutter/Dart dependencies
flutter pub get

# Run the app on a connected device
flutter run

6f. Grant Android Permissions (First Launch)

On first launch, the app will guide you through a permissions screen. You need to grant:

# Permission Where to Enable
1 Usage Access Settings → Apps → Special app access → Usage access → AxeP → Allow
2 Accessibility Service Settings → Accessibility → Installed apps → AxeP → Enable
3 Notifications Prompted automatically on Android 13+
4 Camera Prompted when opening QR scanner

⚠️ Accessibility Service is critical — without it, keyboard entropy tracking and screen text extraction won't work.

6g. Pair with Laptop (Optional)

To sync the phone with the laptop dashboard in real time:

  1. Ensure both phone and laptop are on the same Wi-Fi network
  2. Start the backend server (Step 2) and web frontend (Step 4)
  3. Open the web app at http://<laptop-LAN-IP>:3000/pair (use LAN IP, not localhost)
  4. On the phone, tap the QR scanner icon (top-right of the session setup screen)
  5. Scan the QR code displayed on the web page
  6. The phone connects via WebSocket and streams session data to the laptop

6h. Build a Release APK

cd axep

# Build a release APK
flutter build apk --release

# The APK is at:
# build/app/outputs/flutter-apk/app-release.apk

🎯 Verification

Once everything is running:

Desktop Flow

  1. Open http://localhost:3000 in your browser.
  2. Log in with the same credentials you passed to the daemon.
  3. Start a Session.
  4. Type on your keyboard or switch windows — you should see the Cognitive Liquidity Gauge react in real-time on your dashboard.
  5. If CL drops below 40, the AI Interventions panel will appear to let you generate Quizzes or Flashcards via Gemini.

Mobile Flow

  1. Launch the AxeP app on your phone.
  2. Grant all required permissions (Usage Access, Accessibility, Notifications).
  3. Select your productive apps and tap Start Session.
  4. Switch between apps — you should see the CL gauge update in real-time on the session screen.
  5. After 3+ distraction switches, a quiz notification should appear.
  6. (Optional) Pair with the laptop via QR to see phone metrics on the web dashboard.