.. _setup:

Setup & Installation
====================

Prerequisites
-------------

- Python 3.10 or later
- Flutter SDK 3.9 or later
- A `Supabase <https://supabase.com>`_ project (free tier is sufficient)
- Google Cloud project with OAuth 2.0 credentials (for Google Sign-In)

Backend Setup
-------------

1. Clone the repository and enter the backend directory:

   .. code-block:: bash

      git clone <repo-url>
      cd LinguaAI/backend

2. Create and activate a virtual environment:

   .. code-block:: bash

      # macOS / Linux
      python -m venv venv
      source venv/bin/activate

      # Windows
      python -m venv venv
      venv\Scripts\activate

3. Install dependencies:

   .. code-block:: bash

      pip install -r requirements.txt

4. Create a ``.env`` file in ``backend/`` with the following variables:

   .. code-block:: ini

      SUPABASE_URL=https://<project-ref>.supabase.co
      SUPABASE_KEY=<service_role_key>
      CLIENT_ID=<google_oauth_web_client_id>
      CLIENT_ID_AND=<google_oauth_android_client_id>
      SECRET_KEY=<google_oauth_secret>
      JWT_SECRET_KEY=<your_random_secret>
      RESEND_API_KEY=<resend_email_api_key>
      EMAIL_FROM=onboarding@resend.dev

   .. warning::

      Use the **service role** key for ``SUPABASE_KEY``. This key bypasses Row Level
      Security and must never be exposed to the client.

5. Apply database migrations:

   .. code-block:: bash

      # Requires the Supabase CLI (https://supabase.com/docs/guides/cli)
      supabase db push

6. Start the development server:

   .. code-block:: bash

      uvicorn app.main:app --reload

   The API will be available at ``http://127.0.0.1:8000``.
   Interactive documentation (Swagger UI) is at ``http://127.0.0.1:8000/docs``.

Environment Variables Reference — Backend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Variable
     - Required
     - Description
   * - ``SUPABASE_URL``
     - Yes
     - Full URL of the Supabase project (e.g. ``https://xyz.supabase.co``)
   * - ``SUPABASE_KEY``
     - Yes
     - Supabase **service role** secret key
   * - ``CLIENT_ID``
     - Yes
     - Google OAuth 2.0 web client ID
   * - ``CLIENT_ID_AND``
     - Yes
     - Google OAuth 2.0 Android client ID
   * - ``SECRET_KEY``
     - Yes
     - Google OAuth client secret
   * - ``JWT_SECRET_KEY``
     - Yes
     - Secret used to sign JWTs (min. 32 random characters recommended)
   * - ``RESEND_API_KEY``
     - No
     - API key for Resend to send welcome emails
   * - ``EMAIL_FROM``
     - No
     - Sender email address for welcome emails (default: ``onboarding@resend.dev``)

Frontend Setup
--------------

1. Enter the frontend directory:

   .. code-block:: bash

      cd LinguaAI/frontend

2. Install Flutter dependencies:

   .. code-block:: bash

      flutter pub get

3. Create a ``.env`` file in ``frontend/`` with the following variables:

   .. code-block:: ini

      SUPABASE_URL=https://<project-ref>.supabase.co
      SUPABASE_KEY=<anon_key>
      CLIENT_WEB=<google_oauth_web_client_id>
      CLIENT_ANDROID=<google_oauth_android_client_id>
      SECRET_KEY=<google_oauth_secret>

   .. note::

      Use the **anon** key for ``SUPABASE_KEY`` in the frontend. Row Level Security
      policies determine what the anonymous key can access.

4. Update ``lib/services/api_config.dart`` to point to your backend:

   .. code-block:: dart

      static const String baseUrl = 'http://<your-backend-host>:8000';

5. Run the application:

   .. code-block:: bash

      flutter run             # Connected device or emulator
      flutter run -d chrome   # Web browser

Environment Variables Reference — Frontend
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 25 15 60

   * - Variable
     - Required
     - Description
   * - ``SUPABASE_URL``
     - Yes
     - Full URL of the Supabase project
   * - ``SUPABASE_KEY``
     - Yes
     - Supabase **anon** (public) key
   * - ``CLIENT_WEB``
     - Yes
     - Google OAuth 2.0 web client ID
   * - ``CLIENT_ANDROID``
     - Yes
     - Google OAuth 2.0 Android client ID
   * - ``SECRET_KEY``
     - Yes
     - Google OAuth client secret

Useful Commands
---------------

.. list-table::
   :header-rows: 1
   :widths: 50 50

   * - Command
     - Description
   * - ``uvicorn app.main:app --reload``
     - Start backend dev server with hot-reload
   * - ``pytest``
     - Run all backend tests
   * - ``pytest tests/unit/test_auth_module.py``
     - Run a single test file
   * - ``pytest -k "test_signup"``
     - Run tests matching a name pattern
   * - ``flutter pub get``
     - Install/update Flutter packages
   * - ``flutter run -d chrome``
     - Run the app as a web app
   * - ``flutter analyze``
     - Lint the Flutter codebase
   * - ``flutter build apk``
     - Build an Android APK

Deployment
----------

A CI/CD workflow is available in `.github/workflows/deploy.yml` which deploys the backend using Docker. 
To build and run the Docker container manually:

.. code-block:: bash

   cd LinguaAI/backend
   docker build -t linguaai-backend .
   docker run --env-file .env -d -p 8000:8000 linguaai-backend