Setup & Installation

Prerequisites

• Python 3.10 or later

• Flutter SDK 3.9 or later

• A Supabase 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:

   git clone <repo-url>
   cd LinguaAI/backend
   

2. Create and activate a virtual environment:

   # macOS / Linux
   python -m venv venv
   source venv/bin/activate
   
   # Windows
   python -m venv venv
   venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

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

   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:

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

6. Start the development server:

   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

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:

   cd LinguaAI/frontend
   

2. Install Flutter dependencies:

   flutter pub get
   

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

   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:

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

5. Run the application:

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

Environment Variables Reference — Frontend

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

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:

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