Add: add comprehensive Gmail API documentation and polling setup guides (#45 #46)

app/src/polling/README.md

@@ -0,0 +1,30 @@
+# Gmail Polling System
+
+This module is responsible for performing periodic queries (polling) to the Gmail API to detect, process, and manage emails automatically.
+
+## Overview
+The system utilizes official Google libraries to authenticate, list messages, and download their content. For this component to function correctly, it is mandatory to configure the environment in the **Google Cloud Console** and generate local access credentials.
+
+---
+
+## Environment Setup
+
+To get this system up and running, you must follow these two mandatory configuration processes:
+
+### 1. Google Cloud Project Configuration
+Before running the code, you must enable the Gmail API and configure the OAuth consent screen in the Google Console.
+* **Detailed Guide:** [Google Cloud Setup](./docs/google_cloud_setup.md)
+
+### 2. Access Token Generation (`token.pickle`)
+The system uses a session file called `token.pickle` to avoid manual login every time the script is executed.
+* **Step-by-Step Instructions:** [Token Generation and Credentials](./docs/token_generation.md)
+
+---
+
+## Installation
+
+Ensure you have the necessary dependencies installed before running the service (if the requirements.txt is installed correctly there shouldn't be a problem):
+
+```bash
+pip install --upgrade google-api-python-client google-auth-httplib2 google-auth-oauthlib
+```

app/src/polling/docs/google_cloud_setup.md

@@ -0,0 +1,52 @@
+# Google Cloud Setup for Gmail API
+
+This guide provides a step-by-step walkthrough for configuring your Google Cloud project and obtaining the necessary credentials for the Gmail Polling System.
+
+---
+
+## 1. Project Creation and API Activation
+To begin, you must create a project in the **Google Cloud Console**. This project acts as the container for your application's API configuration and billing settings.
+
+1.  Navigate to the [Google Cloud Console](https://console.cloud.google.com/).
+2.  Create a new project (e.g., "Gmail-Polling-Service").
+3.  Go to the **APIs & Services** section from the sidebar.
+4.  Click on **Enable APIs and Services** and search for **"Gmail API"**.
+5.  Select it and click **Enable**. Once enabled, you will see the API status as "Enabled" in the dashboard.
+
+---
+
+## 2. OAuth Consent Screen Configuration
+Before generating credentials, you must define how the application requests access to user data.
+
+1.  Navigate to **APIs & Services > OAuth Consent Screen**.
+2.  Select **User Type** (typically "External" for development or testing).
+3.  Provide the required branding information (App Name, User Support Email).
+4.  In the **Scopes** (Data Access) section, click **Add or Remove Scopes**.
+5.  Add the following specific permissions required for this system:
+    *   `.../auth/gmail.send`: Allows the application to send emails on your behalf.
+    *   `.../auth/gmail.readonly`: Allows the application to view email messages and settings.
+6.  Ensure your email address is added to the **Test Users** section to allow access during the development phase.
+
+---
+
+## 3. Generating OAuth 2.0 Credentials
+Once the consent screen is configured, you need to create the client credentials that your code will use to identify itself.
+
+1.  Navigate to **APIs & Services > Credentials**.
+2.  Click on **+ Create Credentials** at the top of the screen.
+3.  Select **OAuth Client ID**.
+4.  Choose **Desktop App** as the Application Type.
+5.  Assign a name to your credential (e.g., "Gmail Polling Client").
+
+---
+
+## 4. Downloading the Credentials File
+After creating the OAuth Client ID, a dialog will appear with your Client ID and Client Secret.
+
+1.  **Crucial Step:** Click the **Download JSON** button.
+2.  The downloaded file contains sensitive configuration data. 
+3.  **Rename** this file to `token.json`.
+4.  Place the `token.json` file in the **app directory** of the project.
+
+> [!WARNING]
+> **Security Reminder:** The `token.json` file grants access to your Google Cloud Project. Never commit this file to public version control systems (like GitHub). Verify it is listed in your `.gitignore`.

app/src/polling/docs/token_generation.md

@@ -0,0 +1,69 @@
+# Token Generation Guide
+
+To authenticate the system with the Gmail API, you must generate a `token.pickle` file. This process **must be performed on your local machine** (not via Docker) because the script needs to open a physical web browser window to complete the Google OAuth2 flow.
+
+---
+
+## Prerequisites
+
+Before starting, ensure you have:
+1. Followed the [Google Cloud Setup](./google_cloud_setup.md) guide.
+2. Placed your `token.json` in the appropriate directory.
+
+> [!IMPORTANT]
+> You must run this locally, as a headless Docker container cannot open a browser window for you to log in.
+
+---
+
+## Method A: Using the Project Environment
+
+If you have already set up the full project locally with all dependencies:
+
+1. Open your terminal in the project root.
+2. Ensure your `requirements.txt` dependencies are installed:
+   ```bash
+   pip install -r requirements.txt
+   ```
+3. Run the whole project from the app directory:
+   ```bash
+   uvicorn main:app --reload
+   ```
+
+---
+
+## Method B: Using a Clean Virtual Environment (Recommended)
+
+If you want to generate the token without setting up the entire project:
+
+1. Create and activate a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+2. Install only the necessary libraries for the token creation:
+   ```bash
+   pip install google-auth-oauthlib google-api-python-client
+   ```
+3. Run the script inside the directory app/src/polling:
+   ```bash
+   python generate_token.py
+   ```
+
+---
+
+## The Authentication Flow
+
+Regardless of the method chosen, the following will happen during the process:
+
+* **Browser Redirection:** A tab will automatically open in your default web browser.
+* **Google Login:** You must log in using the **exact same Gmail account** that you added as a "Test User" in the Google Cloud Console.
+* **Permissions:** You will see a prompt asking for permission to access your Gmail data (specifically the `gmail.modify` scope). Click **Allow**.
+* **Completion:** Once the browser displays the message "The authentication flow has completed," you can safely close the tab.
+
+The script will then generate the `token.pickle` file in your local directory, you will need to move it into the app directory:
+```bash
+mv token.pickle ../../
+```
+
+> [!CAUTION]
+> If you ever change the API Scopes in your code, you must delete the existing token.pickle and repeat this local process to grant the new permissions.

app/src/polling/generate_token.py

@@ -0,0 +1,30 @@
+import pickle
+import os
+from google_auth_oauthlib.flow import InstalledAppFlow
+
+SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]
+
+
+def generate_token():
+    creds = None
+
+    client_secrets_file = "../../token.json"
+
+    if not os.path.exists(client_secrets_file):
+        print(
+            f"Error: '{client_secrets_file}' not found. Please follow the Google Cloud Setup guide."
+        )
+        return
+
+    print("Opening browser for authentication...")
+    flow = InstalledAppFlow.from_client_secrets_file(client_secrets_file, SCOPES)
+    creds = flow.run_local_server(port=0)
+
+    with open("token.pickle", "wb") as token:
+        pickle.dump(creds, token)
+
+    print("\nSuccess: 'token.pickle' has been generated!")
+
+
+if __name__ == "__main__":
+    generate_token()