Add migrations for Google Ads settings and demo data

- Create migration for global settings table and add google_ads_customer_id and google_ads_start_date columns to clients table. - Add migration to include product_url column in products_data table. - Insert demo data for campaigns, products, and their history for client 'pomysloweprezenty.pl'. - Implement client management interface with modals for adding and editing clients, including Google Ads Customer ID and data retrieval start date.
2026-02-15 17:46:32 +01:00
parent 32f25dc48c
commit afe9d6216d
32 changed files with 8088 additions and 2288 deletions
--- a/docs/PLAN.md
+++ b/docs/PLAN.md
@@ -0,0 +1,280 @@
+# adsPRO - System Zarządzania Reklamami Google ADS & Facebook ADS
+
+## Opis projektu
+adsPRO to narzędzie webowe (PHP) do zarządzania i automatyzacji kampanii reklamowych Google ADS (priorytet) oraz Facebook ADS (planowane). System umożliwia monitorowanie kampanii, zarządzanie produktami, analizę wydajności (ROAS, CTR, CPC) oraz automatyczne etykietowanie produktów (bestsellery, zombie itp.).
+
+**URL:** https://adspro.projectpro.pl
+**Hosting:** Hostido (shared hosting)
+
+## Stack technologiczny
+- **PHP 8.x** - czyste PHP z własną strukturą MVC (bez frameworka)
+- **MySQL/MariaDB** - baza danych (Medoo ORM)
+- **Google ADS API** - pobieranie danych kampanii i produktów (CRON)
+- **Facebook ADS API** - planowane w przyszłości
+- **CRON** - automatyczna synchronizacja danych
+- **SCSS** - stylowanie (kompilacja do CSS)
+- **jQuery 3.6** - interaktywność frontend
+- **DataTables 2.1.7** - tabele z sortowaniem, filtrowaniem, paginacją
+- **Highcharts** - wykresy wydajności
+- **Select2** - zaawansowane selecty
+- **Font Awesome** - ikony
+
+## Struktura katalogów (nowa)
+
+```
+public_html/
+├── index.php                   # Front controller + nowy router
+├── .htaccess                   # Rewrite rules
+├── .env                        # Konfiguracja (przyszłość - migracja z config.php)
+├── config.php                  # Konfiguracja DB (obecna)
+├── ajax.php                    # Ajax handler
+├── api.php                     # API handler (Google ADS webhook)
+├── cron.php                    # CRON handler
+├── robots.txt
+├── layout/
+│   ├── favicon.png
+│   ├── style.scss              # Główne style (SCSS)
+│   └── style.css               # Skompilowane style
+├── libraries/                  # Biblioteki zewnętrzne
+│   ├── medoo/
+│   ├── phpmailer/
+│   ├── select2/
+│   ├── jquery-confirm/
+│   ├── functions.js            # Globalne funkcje JS
+│   └── framework/              # Framework UI (skin, pluginy)
+├── autoload/                   # Kod PHP (MVC)
+│   ├── class.S.php             # Helper: sesje, requesty, narzędzia
+│   ├── class.Tpl.php           # Template engine
+│   ├── class.Cache.php         # Cache
+│   ├── class.DbModel.php       # Bazowy model DB
+│   ├── class.Html.php          # HTML helper
+│   ├── controls/               # Kontrolery
+│   │   ├── class.Site.php      # Router (do przebudowy)
+│   │   ├── class.Users.php     # Logowanie, ustawienia
+│   │   ├── class.Dashboard.php # NOWY - Dashboard główny
+│   │   ├── class.Campaigns.php # Kampanie Google ADS
+│   │   ├── class.Products.php  # Produkty
+│   │   ├── class.Allegro.php   # Import Allegro
+│   │   ├── class.Reports.php   # NOWY - Raporty i analityka
+│   │   ├── class.Api.php       # Endpointy API
+│   │   └── class.Cron.php      # CRON joby
+│   ├── factory/                # Modele danych (DB queries)
+│   │   ├── class.Users.php
+│   │   ├── class.Campaigns.php
+│   │   ├── class.Products.php
+│   │   └── class.Cron.php
+│   └── view/                   # View helpers
+│       ├── class.Site.php      # Renderer layoutu
+│       ├── class.Users.php
+│       └── class.Cron.php
+├── templates/                  # Szablony PHP
+│   ├── site/
+│   │   ├── layout-logged.php   # Layout z sidebar (PRZEBUDOWA)
+│   │   └── layout-unlogged.php # Layout logowania (PRZEBUDOWA)
+│   ├── auth/
+│   │   └── login.php           # NOWY ekran logowania
+│   ├── dashboard/
+│   │   └── index.php           # NOWY dashboard
+│   ├── campaigns/
+│   │   └── main_view.php       # Widok kampanii
+│   ├── products/
+│   │   ├── main_view.php       # Lista produktów
+│   │   └── product_history.php # Historia produktu
+│   ├── allegro/
+│   │   └── main_view.php       # Import Allegro
+│   ├── reports/                # NOWE
+│   │   └── index.php           # Raporty
+│   ├── users/
+│   │   ├── login-form.php      # Stary login (do usunięcia)
+│   │   └── settings.php        # Ustawienia użytkownika
+│   └── html/                   # Komponenty HTML
+│       ├── button.php
+│       ├── input.php
+│       ├── select.php
+│       └── ...
+├── tools/
+│   └── google-taxonomy.php
+├── tmp/
+└── docs/
+    └── PLAN.md
+```
+
+## Nowy system routingu
+
+### Zasada działania
+Zamiast obecnego `?module=X&action=Y` → czyste URLe obsługiwane przez `.htaccess` + nowy router w `class.Site.php`.
+
+### Mapa URL
+
+| URL | Kontroler | Metoda | Opis |
+|-----|-----------|--------|------|
+| `/login` | Users | login_form | Ekran logowania |
+| `/logout` | Users | logout | Wylogowanie |
+| `/` | Dashboard | index | Dashboard główny |
+| `/campaigns` | Campaigns | main_view | Lista kampanii |
+| `/campaigns/history/{id}` | Campaigns | history | Historia kampanii |
+| `/products` | Products | main_view | Lista produktów |
+| `/products/history/{id}` | Products | product_history | Historia produktu |
+| `/allegro` | Allegro | main_view | Import Allegro |
+| `/reports` | Reports | index | Raporty |
+| `/settings` | Users | settings | Ustawienia konta |
+| `/api/*` | Api | * | Endpointy API |
+| `/cron/*` | Cron | * | CRON joby |
+
+### Nowy .htaccess
+```apache
+RewriteEngine On
+RewriteBase /
+
+# Statyczne zasoby - pomijaj
+RewriteCond %{REQUEST_URI} ^/(libraries|layout|upload|temp)/ [NC]
+RewriteRule ^ - [L]
+
+# Wszystko inne → index.php
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+RewriteRule ^(.*)$ index.php [L,QSA]
+```
+
+### Nowy router (class.Site.php)
+```php
+// Parsowanie URL z $_SERVER['REQUEST_URI']
+// Mapowanie: /segment1/segment2/segment3 → kontroler/akcja/parametry
+// Fallback na dashboard dla zalogowanych, login dla niezalogowanych
+```
+
+## Główne funkcje
+
+### 1. Nowy ekran logowania
+- Nowoczesny design: podzielony ekran (lewa strona - branding/grafika, prawa - formularz)
+- Logo "adsPRO" z subtitlem
+- Pola: email + hasło
+- Checkbox "Zapamiętaj mnie"
+- Walidacja AJAX
+- Animacje przejścia
+- Responsywność (mobile: tylko formularz)
+
+### 2. Nowy layout z menu bocznym (sidebar)
+- **Sidebar (lewa strona, 260px):**
+  - Logo "adsPRO" na górze
+  - Menu nawigacyjne z ikonami Font Awesome:
+    - 📊 Dashboard (`/`)
+    - 📢 Kampanie (`/campaigns`)
+    - 📦 Produkty (`/products`)
+    - 📥 Allegro import (`/allegro`)
+    - 📈 Raporty (`/reports`)
+    - ⚙️ Ustawienia (`/settings`)
+  - Aktywny element podświetlony
+  - Możliwość zwijania sidebar (collapsed → same ikony, 60px)
+  - Na dole: info o zalogowanym użytkowniku + przycisk wylogowania
+- **Top bar (nad contentem):**
+  - Przycisk hamburger (toggle sidebar)
+  - Breadcrumbs (ścieżka nawigacji)
+  - Szybkie akcje / notyfikacje (przyszłość)
+- **Content area:**
+  - Pełna szerokość minus sidebar
+  - Padding 25px
+  - Tło #F4F6F9 (jaśniejsze od obecnego)
+
+### 3. Dashboard (NOWY)
+- Kafelki podsumowujące (karty):
+  - Łączna liczba kampanii
+  - Łączna liczba produktów
+  - Średni ROAS (30 dni)
+  - Łączne wydatki (30 dni)
+- Wykres trendu ROAS (ostatnie 30 dni)
+- Lista ostatnio zmodyfikowanych kampanii
+- Produkty wymagające uwagi (niski ROAS, zombie)
+
+### 4. Zarządzanie kampaniami Google ADS
+- Wybór klienta (select)
+- Lista kampanii z metrykami (DataTables)
+- Historia kampanii z wykresem Highcharts
+- Metryki: ROAS, budżet, wydatki, wartość konwersji, strategia bidding
+- Usuwanie kampanii i wpisów historii
+- Komentarze do kampanii
+
+### 5. Zarządzanie produktami
+- Wybór klienta
+- Konfiguracja min. ROAS dla bestsellerów
+- Tabela produktów z metrykami:
+  - Wyświetlenia, kliknięcia, CTR, koszt, CPC
+  - Konwersje, wartość konwersji, ROAS
+  - Custom labels (bestseller/zombie/deleted/pla/paused)
+- Edycja inline (min_roas, custom_label)
+- Edycja produktu w modalu (tytuł, opis, kategoria Google)
+- Historia produktu z wykresem
+- Bulk delete zaznaczonych produktów
+
+### 6. Import Allegro
+- Upload pliku CSV
+- Automatyczne mapowanie ofert
+- Raport importu (dodane, zaktualizowane)
+
+### 7. Raporty (NOWY - przyszłość)
+- Raport wydajności kampanii
+- Raport produktów (bestsellery vs zombie)
+- Eksport do Excel
+- Porównanie okresów
+
+### 8. Ustawienia
+- Dane konta (email)
+- Zmiana hasła
+- Konfiguracja Pushover (powiadomienia)
+- Klucze API (przyszłość: Google ADS, Facebook ADS)
+
+### 9. CRON - synchronizacja danych
+- `cron_products` - synchronizacja produktów z Google ADS
+- `cron_products_history_30` - historia 30-dniowa produktów
+- `cron_xml` - generowanie XML
+- `cron_phrases` - synchronizacja fraz
+- `cron_phrases_history_30` - historia 30-dniowa fraz
+
+## Plan implementacji
+
+| Etap | Zakres | Priorytet | Pliki |
+|------|--------|-----------|-------|
+| **1. Nowy routing** | Przebudowa routera, nowy .htaccess, parsowanie czystych URL | 🔴 Wysoki | `.htaccess`, `index.php`, `controls/class.Site.php` |
+| **2. Nowy layout (sidebar)** | Layout z bocznym menu, top bar, responsywność | 🔴 Wysoki | `templates/site/layout-logged.php`, `layout/style.scss` |
+| **3. Nowy ekran logowania** | Nowoczesny split-screen login, nowy layout-unlogged | 🔴 Wysoki | `templates/site/layout-unlogged.php`, `templates/auth/login.php`, `layout/style.scss` |
+| **4. Dashboard** | Nowa strona startowa z podsumowaniem | 🟡 Średni | `controls/class.Dashboard.php`, `templates/dashboard/index.php` |
+| **5. Migracja kampanii** | Dostosowanie widoku kampanii do nowego routingu | 🟡 Średni | `controls/class.Campaigns.php`, `templates/campaigns/*` |
+| **6. Migracja produktów** | Dostosowanie widoku produktów do nowego routingu | 🟡 Średni | `controls/class.Products.php`, `templates/products/*` |
+| **7. Migracja Allegro** | Dostosowanie importu Allegro | 🟢 Niski | `controls/class.Allegro.php`, `templates/allegro/*` |
+| **8. Moduł raportów** | Nowy moduł analityczny | 🟢 Niski | `controls/class.Reports.php`, `templates/reports/*` |
+| **9. Facebook ADS** | Integracja z Facebook ADS API | 🔵 Przyszłość | Nowe kontrolery, factory, szablony |
+
+## Kolorystyka i design
+
+### Paleta kolorów
+- **Primary (akcent):** `#6690F4` (niebieski - obecny)
+- **Sidebar tło:** `#1E2A3A` (ciemny granat)
+- **Sidebar tekst:** `#A8B7C7` (jasny szary)
+- **Sidebar active:** `#6690F4` (primary)
+- **Content tło:** `#F4F6F9` (jasnoszary)
+- **Karty:** `#FFFFFF`
+- **Tekst:** `#4E5E6A` (obecny)
+- **Success:** `#57B951`
+- **Danger:** `#CC0000`
+- **Warning:** `#FF8C00`
+
+### Typografia
+- Font: Open Sans (obecny - zachowany)
+- Rozmiar bazowy: 14px (sidebar), 15px (content)
+
+## Bezpieczeństwo
+- Hasła hashowane MD5 (obecne) → **TODO: migracja na bcrypt**
+- Sesje PHP + cookie "zapamiętaj mnie"
+- Prepared statements (Medoo ORM)
+- htmlspecialchars() w szablonach
+- **TODO: CSRF tokeny w formularzach**
+- **TODO: migracja config.php → .env (z .htaccess deny)**
+
+## Przyszłe rozszerzenia
+- Facebook ADS API - zarządzanie kampaniami FB
+- System powiadomień (Pushover + in-app)
+- Wielojęzyczność (PL/EN)
+- Role użytkowników (admin, manager, viewer)
+- Automatyczne reguły (np. "jeśli ROAS < X → zmień label na zombie")
+- Integracja z Google Merchant Center
+- API REST do integracji z innymi systemami
--- a/docs/google_ads_api_design_doc.doc
+++ b/docs/google_ads_api_design_doc.doc
@@ -0,0 +1,153 @@
+<html xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns="http://www.w3.org/TR/REC-html40">
+<head>
+<meta charset="utf-8">
+<style>
+  body { font-family: Calibri, sans-serif; font-size: 11pt; color: #333; line-height: 1.6; margin: 40px; }
+  h1 { font-size: 20pt; color: #1a73e8; border-bottom: 2px solid #1a73e8; padding-bottom: 8px; }
+  h2 { font-size: 14pt; color: #1a73e8; margin-top: 24px; }
+  h3 { font-size: 12pt; color: #444; margin-top: 16px; }
+  p { margin: 6px 0; }
+  ul { margin: 6px 0 6px 20px; }
+  li { margin: 4px 0; }
+  strong { color: #222; }
+  code { font-family: Consolas, monospace; font-size: 10pt; background: #f5f5f5; padding: 2px 4px; }
+  pre { font-family: Consolas, monospace; font-size: 9.5pt; background: #f8f8f8; border: 1px solid #ddd; padding: 12px; margin: 10px 0; white-space: pre-wrap; }
+  hr { border: none; border-top: 1px solid #ccc; margin: 16px 0; }
+  .meta { color: #666; font-size: 10pt; }
+</style>
+</head>
+<body>
+
+<h1>adsPRO &mdash; Google Ads API Tool Design Documentation</h1>
+
+<p class="meta"><strong>Company:</strong> Project-Pro<br>
+<strong>Tool Name:</strong> adsPRO<br>
+<strong>Date:</strong> February 2026<br>
+<strong>Version:</strong> 1.0</p>
+
+<hr>
+
+<h2>1. Tool Overview</h2>
+
+<p>adsPRO is an internal advertising management platform built for our agency to centralize and automate the management of Google Ads campaigns across multiple client accounts. The tool provides a unified dashboard for monitoring campaign performance, analyzing key metrics (ROAS, cost, conversion value), and managing campaign settings &mdash; eliminating the need to switch between multiple Google Ads accounts manually.</p>
+
+<h2>2. Purpose and Business Use Case</h2>
+
+<p>Our agency manages Google Ads campaigns for multiple clients. Currently, campaign data is collected manually or via Google Apps Script, which is fragile and hard to maintain. adsPRO replaces this workflow with a direct, reliable integration with the Google Ads API.</p>
+
+<p><strong>Key goals:</strong></p>
+<ul>
+  <li>Automatically retrieve campaign performance data for all managed client accounts</li>
+  <li>Display historical trends (ROAS, budget, spend, conversions) in a centralized dashboard</li>
+  <li>Enable campaign management operations (budget adjustments, bidding strategy changes, campaign status updates) directly from the platform</li>
+  <li>Reduce manual work and improve response time for campaign optimization</li>
+</ul>
+
+<h2>3. Google Ads API Usage</h2>
+
+<h3>3.1 Data Retrieval (Read Operations)</h3>
+
+<p>The tool uses the <strong>GoogleAdsService.SearchStream</strong> endpoint to fetch campaign data using GAQL (Google Ads Query Language).</p>
+
+<p><strong>Data retrieved:</strong></p>
+<ul>
+  <li>Campaign name, ID, and status</li>
+  <li>Bidding strategy type and target ROAS</li>
+  <li>Campaign budget (daily)</li>
+  <li>Cost (spend) over the last 30 days</li>
+  <li>Conversion value over the last 30 days</li>
+  <li>All-time ROAS calculation</li>
+</ul>
+
+<p><strong>GAQL queries used:</strong></p>
+
+<pre>SELECT campaign.id, campaign.name, campaign.bidding_strategy_type,
+       campaign.target_roas.target_roas, campaign_budget.amount_micros,
+       metrics.cost_micros, metrics.conversions_value
+FROM campaign
+WHERE campaign.status = 'ENABLED'
+  AND segments.date DURING LAST_30_DAYS</pre>
+
+<pre>SELECT campaign.id, metrics.cost_micros, metrics.conversions_value
+FROM campaign
+WHERE campaign.status = 'ENABLED'</pre>
+
+<h3>3.2 Campaign Management (Write Operations)</h3>
+
+<p>The tool will also support campaign management operations through the Google Ads API:</p>
+
+<ul>
+  <li><strong>Budget adjustments</strong> &mdash; updating <code>campaign_budget.amount_micros</code> via <code>CampaignBudgetService.MutateCampaignBudgets</code></li>
+  <li><strong>Bidding strategy changes</strong> &mdash; modifying bidding strategy type and target ROAS via <code>CampaignService.MutateCampaigns</code></li>
+  <li><strong>Campaign status updates</strong> &mdash; enabling/pausing campaigns via <code>CampaignService.MutateCampaigns</code></li>
+</ul>
+
+<p>All write operations are initiated manually by authorized agency staff through the adsPRO interface. No automated modifications are made without human approval.</p>
+
+<h2>4. API Request Frequency</h2>
+
+<ul>
+  <li><strong>Automated data retrieval:</strong> Once per day via server-side CRON job (scheduled at 06:00 CET)</li>
+  <li><strong>Campaign management operations:</strong> On-demand, initiated manually by agency staff (estimated 10&ndash;50 requests per day)</li>
+  <li><strong>Number of client accounts:</strong> Currently under 20, expected to grow to ~50</li>
+  <li><strong>Estimated total daily API calls:</strong> Under 200 requests per day</li>
+</ul>
+
+<h2>5. Authentication and Authorization</h2>
+
+<ul>
+  <li>OAuth 2.0 authentication with offline access (refresh token flow)</li>
+  <li>Credentials stored securely in a server-side database (not exposed to end users)</li>
+  <li>Access token is refreshed automatically when expired</li>
+  <li>Optional Manager Account (MCC) support for centralized access to client accounts</li>
+</ul>
+
+<h2>6. Architecture</h2>
+
+<pre>[CRON - daily at 06:00]
+        |
+        v
+[adsPRO Server (PHP)]
+        |
+        v
+[Google Ads REST API v18]
+   - SearchStream (read campaign data)
+   - MutateCampaigns (manage campaigns)
+   - MutateCampaignBudgets (adjust budgets)
+        |
+        v
+[MySQL Database]
+   - campaigns table (current state)
+   - campaigns_history table (daily snapshots)
+        |
+        v
+[adsPRO Dashboard]
+   - Campaign performance charts
+   - ROAS tracking over time
+   - Campaign management interface</pre>
+
+<h2>7. Data Handling and Privacy</h2>
+
+<ul>
+  <li>All data is stored on our own private server (shared hosting with SSL)</li>
+  <li>Data is accessible only to authenticated agency staff (login required)</li>
+  <li>No campaign data is shared with third parties</li>
+  <li>No personally identifiable information (PII) is collected from end users</li>
+  <li>API credentials are stored server-side and never exposed in client-facing code</li>
+</ul>
+
+<h2>8. Users</h2>
+
+<p>This is an <strong>internal agency tool</strong>. It is not a publicly available application. Access is restricted to authorized staff members of our agency (currently 3 users). There is no self-registration &mdash; accounts are created by the administrator.</p>
+
+<h2>9. Compliance</h2>
+
+<ul>
+  <li>The tool complies with the Google Ads API Terms of Service</li>
+  <li>The tool complies with the Google API Services User Data Policy</li>
+  <li>No data is sold or shared with third parties</li>
+  <li>The tool does not perform automated campaign modifications without human oversight</li>
+</ul>
+
+</body>
+</html>
--- a/docs/google_ads_api_design_doc.md
+++ b/docs/google_ads_api_design_doc.md
@@ -0,0 +1,122 @@
+# adsPRO — Google Ads API Tool Design Documentation
+
+**Company:** Project-Pro
+**Tool Name:** adsPRO
+**Date:** February 2026
+**Version:** 1.0
+
+---
+
+## 1. Tool Overview
+
+adsPRO is an internal advertising management platform built for our agency to centralize and automate the management of Google Ads campaigns across multiple client accounts. The tool provides a unified dashboard for monitoring campaign performance, analyzing key metrics (ROAS, cost, conversion value), and managing campaign settings — eliminating the need to switch between multiple Google Ads accounts manually.
+
+## 2. Purpose and Business Use Case
+
+Our agency manages Google Ads campaigns for multiple clients. Currently, campaign data is collected manually or via Google Apps Script, which is fragile and hard to maintain. adsPRO replaces this workflow with a direct, reliable integration with the Google Ads API.
+
+**Key goals:**
+- Automatically retrieve campaign performance data for all managed client accounts
+- Display historical trends (ROAS, budget, spend, conversions) in a centralized dashboard
+- Enable campaign management operations (budget adjustments, bidding strategy changes, campaign status updates) directly from the platform
+- Reduce manual work and improve response time for campaign optimization
+
+## 3. Google Ads API Usage
+
+### 3.1 Data Retrieval (Read Operations)
+
+The tool uses the **GoogleAdsService.SearchStream** endpoint to fetch campaign data using GAQL (Google Ads Query Language).
+
+**Data retrieved:**
+- Campaign name, ID, and status
+- Bidding strategy type and target ROAS
+- Campaign budget (daily)
+- Cost (spend) over the last 30 days
+- Conversion value over the last 30 days
+- All-time ROAS calculation
+
+**GAQL queries used:**
+
+```
+SELECT campaign.id, campaign.name, campaign.bidding_strategy_type,
+       campaign.target_roas.target_roas, campaign_budget.amount_micros,
+       metrics.cost_micros, metrics.conversions_value
+FROM campaign
+WHERE campaign.status = 'ENABLED'
+  AND segments.date DURING LAST_30_DAYS
+```
+
+```
+SELECT campaign.id, metrics.cost_micros, metrics.conversions_value
+FROM campaign
+WHERE campaign.status = 'ENABLED'
+```
+
+### 3.2 Campaign Management (Write Operations)
+
+The tool will also support campaign management operations through the Google Ads API:
+
+- **Budget adjustments** — updating `campaign_budget.amount_micros` via `CampaignBudgetService.MutateCampaignBudgets`
+- **Bidding strategy changes** — modifying bidding strategy type and target ROAS via `CampaignService.MutateCampaigns`
+- **Campaign status updates** — enabling/pausing campaigns via `CampaignService.MutateCampaigns`
+
+All write operations are initiated manually by authorized agency staff through the adsPRO interface. No automated modifications are made without human approval.
+
+## 4. API Request Frequency
+
+- **Automated data retrieval:** Once per day via server-side CRON job (scheduled at 06:00 CET)
+- **Campaign management operations:** On-demand, initiated manually by agency staff (estimated 10–50 requests per day)
+- **Number of client accounts:** Currently under 20, expected to grow to ~50
+- **Estimated total daily API calls:** Under 200 requests per day
+
+## 5. Authentication and Authorization
+
+- OAuth 2.0 authentication with offline access (refresh token flow)
+- Credentials stored securely in a server-side database (not exposed to end users)
+- Access token is refreshed automatically when expired
+- Optional Manager Account (MCC) support for centralized access to client accounts
+
+## 6. Architecture
+
+```
+[CRON - daily at 06:00]
+        |
+        v
+[adsPRO Server (PHP)]
+        |
+        v
+[Google Ads REST API v18]
+   - SearchStream (read campaign data)
+   - MutateCampaigns (manage campaigns)
+   - MutateCampaignBudgets (adjust budgets)
+        |
+        v
+[MySQL Database]
+   - campaigns table (current state)
+   - campaigns_history table (daily snapshots)
+        |
+        v
+[adsPRO Dashboard]
+   - Campaign performance charts
+   - ROAS tracking over time
+   - Campaign management interface
+```
+
+## 7. Data Handling and Privacy
+
+- All data is stored on our own private server (shared hosting with SSL)
+- Data is accessible only to authenticated agency staff (login required)
+- No campaign data is shared with third parties
+- No personally identifiable information (PII) is collected from end users
+- API credentials are stored server-side and never exposed in client-facing code
+
+## 8. Users
+
+This is an **internal agency tool**. It is not a publicly available application. Access is restricted to authorized staff members of our agency (currently 3 users). There is no self-registration — accounts are created by the administrator.
+
+## 9. Compliance
+
+- The tool complies with the Google Ads API Terms of Service
+- The tool complies with the Google API Services User Data Policy
+- No data is sold or shared with third parties
+- The tool does not perform automated campaign modifications without human oversight