# kothakula-sagar/abra-zylo-seo-generator architecture

> Architecture diagram of the GitHub repository kothakula-sagar/abra-zylo-seo-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kothakula-sagar/abra-zylo-seo-generator
- Repository: https://github.com/kothakula-sagar/abra-zylo-seo-generator

## Overview

#### Purpose and principal workflow

Abra Zylo is a browser-based eCommerce SEO portal. A user opens the public landing page or the application directly; the landing page’s calls to action lead to the authenticated portal. After signing in, the user can enter product information and an image, generate and validate SEO content, and manage product records and generation history. Separate portal workflows support page and performance audits, campaign preparation, and catalog organization. A standalone storefront demo is also present, but its relationship to the portal is not established.

#### Components

##### Entry points and portal orchestration
- **Public landing page** — `index.html`: Public marketing entry point; the README says its calls to action open the application and that it does not load Firebase or the protected app.
- **SEO Generator portal** — `main.html`: Application entry point documented as containing authentication and the portal’s feature areas.
- **Portal controller** — `js/app.js`: Coordinates authentication-dependent entry, maintenance-state watching, tab selection, and lazy loading of portal modules; its excerpt shows it dispatching to dashboard, generator, audits, history, marketing, and other areas.

##### Identity, persistence, and shared assets
- **Authentication and user profile** — `js/auth.js`: Handles login, registration, password reset, logout, session callbacks, and retrieval of provider API keys; the excerpt shows it using Firebase and UI helpers.
- **Firebase access layer** — `js/firebase.js`: Initializes Firebase Authentication, Firestore, and Firebase Storage, then exposes a shared API for those services.
- **Maintenance controls** — `js/maintenance.js`: Watches portal maintenance state; the app controller uses that watch to respond to state changes.
- **Product model helpers** — `js/product-model.js`: Provides product normalization and model-number checks used by the generator and marketing module, as indicated by their imports.
- **Image upload and transformation** — `js/cloudinary.js`: Implements the shared Cloudinary image service; generator and marketing excerpts show them calling its upload function.

##### Product SEO workflow
- **SEO generation and product workflow** — `js/seo-generator.js`: Builds a product-context prompt, prepares product images, calls AI, checks model-number uniqueness, and supports restoring saved SEO records; imports also show its use of quality, storage, UI, and helper modules.
- **AI provider requests** — `js/ai.js`: Implements the AI-call module imported by the generator; the README documents Groq, Gemini, and OpenRouter as supported providers.
- **SEO quality and factual checks** — `js/seo-quality.js`: Contains deterministic SEO evaluation and fact-prompt logic; the README distinguishes source confirmation and human review from checklist scoring.
- **SEO record handling** — `js/seo-store.js`: Implements SEO storage logic and imports the quality module; the sampled inputs do not show its callers.
- **Generation history and restoration** — `js/history.js`: Displays product generation status and versions and invokes the generator’s restore function for a selected record.

##### Product operations and portal surfaces
- **Products, campaigns, and Meta catalog** — `js/marketing.js`: Implements product management and campaign/catalog workflows; excerpts show product image uploads and product-model normalization.
- **Customer management** — `js/customers.js`: Implements customer-facing portal management operations; the app controller dispatches to its customer view.
- **Dashboard** — `js/dashboard.js`: Loads portal statistics and is invoked by the controller when the dashboard tab is selected.
- **Accounts administration** — `js/accounts.js`: Implements account-management functionality; the app controller dispatches to its view.
- **Settings** — `js/settings.js`: Implements settings, imports Firebase/auth/AI helpers, and is rendered by the controller for the settings tab.

##### Audits and shared interface
- **SEO and performance audits** — `js/audit.js`: Implements audit workflows, including a PageSpeed/Lighthouse run, report display, and audit-history actions.
- **PageSpeed analysis** — `js/pagespeed.js`: Provides the PageSpeed audit function called by the audit module.
- **Performance AI analysis** — `js/performance-ai.js`: A separate performance-analysis module; the excerpt index shows an authentication dependency, but not its caller.
- **Performance audit history** — `js/audit-history.js`: Saves, renders, compares, exports, and deletes performance audit reports using Firebase.
- **Shared UI helpers** — `js/ui.js`: Provides DOM-facing UI functions such as alerts, loading progress, modals, and tab switching.

##### Separate storefront demo
- **Storefront state and commerce rules** — `storefront-demo/store.js`: Holds demo product data and state operations including cart, delivery, checkout validation, stock, and orders.
- **Storefront interface** — `storefront-demo/app.js`: Implements the demo storefront application and imports its state module; the README and sampled inputs do not establish integration with the SEO portal.

#### Relationships

- **External portal user** *(external; null repository path)* -> **Public landing page**: opens the public site; evidence: `README.md`.
- **Public landing page** -> **SEO Generator portal**: its calls to action open the application; evidence: `README.md`.
- **External portal user** *(external; null repository path)* -> **SEO Generator portal**: can open the application directly; evidence: `README.md`.
- **SEO Generator portal** -> **Portal controller**: the README identifies the HTML page as the application entry point and `js/app.js` as its main controller; evidence: none (inferred).
- **Portal controller** -> **Authentication and user profile**: responds to authentication state and routes unauthenticated users to the auth view; evidence: `js/app.js`.
- **Portal controller** -> **Maintenance controls**: starts a maintenance-state watch and responds to state changes; evidence: `js/app.js`.
- **Authentication and user profile** -> **Firebase access layer**: performs authentication operations through Firebase helpers; evidence: `js/auth.js`.
- **Portal controller** -> **Dashboard**: calls `Dashboard.loadStats()` when the dashboard tab is selected; evidence: `js/app.js`.
- **Portal controller** -> **Products, campaigns, and Meta catalog**: dispatches to marketing render functions for those tabs; evidence: `js/app.js`.
- **Portal controller** -> **Customer management**: calls its customer renderer; evidence: `js/app.js`.
- **Portal controller** -> **Accounts administration**: calls its renderer; evidence: `js/app.js`.
- **Portal controller** -> **Settings**: calls its renderer; evidence: `js/app.js`.
- **Portal controller** -> **SEO generation and product workflow**: initializes the generator when the generate tab is selected; evidence: `js/app.js`.
- **SEO generation and product workflow** -> **AI provider requests**: calls the AI module with a product prompt, user key, and provider; evidence: `js/seo-generator.js`.
- **AI provider requests** -> **External AI providers** *(external; null repository path)*: provider choices are documented as Groq, Gemini, and OpenRouter; evidence: `README.md`.
- **SEO generation and product workflow** -> **Image upload and transformation**: uploads product images through the Cloudinary module; evidence: `js/seo-generator.js`.
- **Image upload and transformation** -> **Cloudinary** *(external; null repository path)*: the module implements the Cloudinary service; evidence: `js/cloudinary.js`.
- **SEO generation and product workflow** -> **Product model helpers**: checks model-number uniqueness; evidence: `js/seo-generator.js`.
- **SEO generation and product workflow** -> **SEO quality and factual checks**: imports and uses the factual prompt helper; evidence: `js/seo-generator.js`.
- **Generation history and restoration** -> **SEO generation and product workflow**: invokes the generator’s restore function for a selected record; evidence: `js/history.js`.
- **SEO and performance audits** -> **PageSpeed analysis**: calls the PageSpeed audit function; evidence: `js/audit.js`.
- **PageSpeed analysis** -> **Google PageSpeed Insights** *(external; null repository path)*: PageSpeed/Lighthouse analysis is documented; evidence: `README.md`.
- **SEO and performance audits** -> **Performance audit history**: imports and uses history operations; evidence: `js/audit.js`.
- **Performance audit history** -> **Firebase access layer**: saves and manages report records through Firebase; evidence: `js/audit-history.js`.
- **Storefront interface** -> **Storefront state and commerce rules**: imports the state module; evidence: `storefront-demo/app.js`.

#### Coverage limits

Several modules are represented by the source index or README rather than full excerpts. In particular, the exact generator-to-SEO-storage call path, the callers of performance AI analysis, and the storefront demo’s launch path were not established. No portal-to-storefront integration is shown.

Main entry points: [`js/app.js`](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/app.js) (Portal controller), [`js/seo-generator.js`](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/seo-generator.js) (SEO generation workflow), [`main.html`](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/main.html) (SEO Generator portal), [`js/audit.js`](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/audit.js) (SEO & performance audits)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Portal Entry &amp; Runtime"]
  node_landing["Public landing page<br/>web page"]
  node_portal["SEO Generator portal<br/>web application"]
  node_controller["Portal controller<br/>[app.js]"]
end

subgraph group_identity["Identity &amp; Shared Services"]
  node_auth["Authentication &amp; profile<br/>[auth.js]"]
  node_firebase[("Firebase access layer<br/>database services")]
  node_maintenance["Maintenance controls<br/>state watcher"]
  node_product_model["Product model helpers<br/>domain helpers"]
  node_cloudinary_service["Image upload service<br/>image service"]
end

subgraph group_seo["SEO Product Workflow"]
  node_seo_generator["SEO generation workflow<br/>product workflow"]
  node_ai_requests["AI provider requests<br/>AI client"]
  node_seo_quality["SEO quality checks<br/>[seo-quality.js]"]
  node_seo_store["SEO record handling<br/>record storage"]
  node_history["Generation history<br/>history view"]
end

subgraph group_operations["Portal Operations"]
  node_marketing["Products &amp; campaigns<br/>portal module"]
  node_customers["Customer management<br/>portal module"]
  node_dashboard["Dashboard<br/>portal module"]
  node_accounts["Accounts administration<br/>portal module"]
  node_settings["Settings<br/>portal module"]
end

subgraph group_audits["Audits"]
  node_audit["SEO &amp; performance audits<br/>audit workflow"]
  node_pagespeed["PageSpeed analysis<br/>analysis module"]
  node_audit_history["Performance audit history<br/>report history"]
end

subgraph group_storefront["Storefront Demo"]
  node_storefront_app["Storefront interface<br/>demo application"]
  node_storefront_state["Storefront commerce rules<br/>demo state"]
end

node_portal_user(("Portal user<br/>external actor"))
node_ai_providers["AI providers<br/>external service"]
node_google_pagespeed["Google PageSpeed Insights<br/>external service"]
node_cloudinary["Cloudinary<br/>external service"]

node_portal_user -->|"opens"| node_landing
node_landing -->|"opens via CTA"| node_portal
node_portal_user -->|"opens directly"| node_portal
node_portal -.->|"hands off to"| node_controller
node_controller -->|"routes auth"| node_auth
node_controller -->|"watches state"| node_maintenance
node_auth -->|"uses"| node_firebase
node_controller -->|"loads stats"| node_dashboard
node_controller -->|"dispatches tabs"| node_marketing
node_controller -->|"renders view"| node_customers
node_controller -->|"renders view"| node_accounts
node_controller -->|"renders view"| node_settings
node_controller -->|"initializes"| node_seo_generator
node_seo_generator -->|"calls"| node_ai_requests
node_ai_requests -->|"requests generation"| node_ai_providers
node_seo_generator -->|"uploads images"| node_cloudinary_service
node_cloudinary_service -->|"uses service"| node_cloudinary
node_seo_generator -->|"checks uniqueness"| node_product_model
node_seo_generator -->|"uses fact prompts"| node_seo_quality
node_history -->|"restores record"| node_seo_generator
node_audit -->|"runs analysis"| node_pagespeed
node_pagespeed -->|"analyzes pages"| node_google_pagespeed
node_audit -->|"uses history"| node_audit_history
node_audit_history -->|"manages reports"| node_firebase
node_storefront_app -->|"imports"| node_storefront_state

click node_landing "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/index.html"
click node_portal "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/main.html"
click node_controller "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/app.js"
click node_auth "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/auth.js"
click node_firebase "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/firebase.js"
click node_maintenance "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/maintenance.js"
click node_product_model "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/product-model.js"
click node_cloudinary_service "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/cloudinary.js"
click node_seo_generator "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/seo-generator.js"
click node_ai_requests "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/ai.js"
click node_seo_quality "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/seo-quality.js"
click node_seo_store "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/seo-store.js"
click node_history "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/history.js"
click node_marketing "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/marketing.js"
click node_customers "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/customers.js"
click node_dashboard "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/dashboard.js"
click node_accounts "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/accounts.js"
click node_settings "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/settings.js"
click node_audit "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/audit.js"
click node_pagespeed "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/pagespeed.js"
click node_audit_history "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/audit-history.js"
click node_storefront_app "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/storefront-demo/app.js"
click node_storefront_state "https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/storefront-demo/store.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_landing,node_portal,node_controller,node_portal_user toneBlue
class node_auth,node_firebase,node_maintenance,node_product_model,node_cloudinary_service toneAmber
class node_seo_generator,node_ai_requests,node_seo_quality,node_seo_store,node_history toneMint
class node_marketing,node_customers,node_dashboard,node_accounts,node_settings toneRose
class node_audit,node_pagespeed,node_audit_history,node_ai_providers,node_google_pagespeed,node_cloudinary toneIndigo
class node_storefront_app,node_storefront_state toneTeal
```

## Components

### Portal Entry & Runtime

- [Public landing page](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/index.html): web page · `index.html`
- [SEO Generator portal](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/main.html): web application · `main.html`
- [Portal controller](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/app.js): controller · `js/app.js`

### Identity & Shared Services

- [Authentication & profile](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/auth.js): authentication · `js/auth.js`
- [Firebase access layer](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/firebase.js): database services · `js/firebase.js`
- [Maintenance controls](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/maintenance.js): state watcher · `js/maintenance.js`
- [Product model helpers](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/product-model.js): domain helpers · `js/product-model.js`
- [Image upload service](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/cloudinary.js): image service · `js/cloudinary.js`

### SEO Product Workflow

- [SEO generation workflow](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/seo-generator.js): product workflow · `js/seo-generator.js`
- [AI provider requests](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/ai.js): AI client · `js/ai.js`
- [SEO quality checks](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/seo-quality.js): quality checks · `js/seo-quality.js`
- [SEO record handling](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/seo-store.js): record storage · Sampled inputs do not show its callers. · `js/seo-store.js`
- [Generation history](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/history.js): history view · `js/history.js`

### Portal Operations

- [Products & campaigns](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/marketing.js): portal module · `js/marketing.js`
- [Customer management](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/customers.js): portal module · `js/customers.js`
- [Dashboard](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/dashboard.js): portal module · `js/dashboard.js`
- [Accounts administration](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/accounts.js): portal module · `js/accounts.js`
- [Settings](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/settings.js): portal module · `js/settings.js`

### Audits

- [SEO & performance audits](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/audit.js): audit workflow · `js/audit.js`
- [PageSpeed analysis](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/pagespeed.js): analysis module · `js/pagespeed.js`
- [Performance audit history](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/js/audit-history.js): report history · `js/audit-history.js`

### Storefront Demo

- [Storefront interface](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/storefront-demo/app.js): demo application · `storefront-demo/app.js`
- [Storefront commerce rules](https://github.com/kothakula-sagar/abra-zylo-seo-generator/blob/main/storefront-demo/store.js): demo state · `storefront-demo/store.js`

### Other components

- **Portal user**: external actor
- **AI providers**: external service
- **Google PageSpeed Insights**: external service
- **Cloudinary**: external service

## Connections

- Portal user → Public landing page: opens (evidence: `README.md`)
- Public landing page → SEO Generator portal: opens via CTA (evidence: `README.md`)
- Portal user → SEO Generator portal: opens directly (evidence: `README.md`)
- SEO Generator portal → Portal controller: hands off to · Inferred; not shown in the code that was read.
- Portal controller → Authentication & profile: routes auth (evidence: `js/app.js`)
- Portal controller → Maintenance controls: watches state (evidence: `js/app.js`)
- Authentication & profile → Firebase access layer: uses (evidence: `js/auth.js`)
- Portal controller → Dashboard: loads stats (evidence: `js/app.js`)
- Portal controller → Products & campaigns: dispatches tabs (evidence: `js/app.js`)
- Portal controller → Customer management: renders view (evidence: `js/app.js`)
- Portal controller → Accounts administration: renders view (evidence: `js/app.js`)
- Portal controller → Settings: renders view (evidence: `js/app.js`)
- Portal controller → SEO generation workflow: initializes (evidence: `js/app.js`)
- SEO generation workflow → AI provider requests: calls (evidence: `js/seo-generator.js`)
- AI provider requests → AI providers: requests generation (evidence: `README.md`)
- SEO generation workflow → Image upload service: uploads images (evidence: `js/seo-generator.js`)
- Image upload service → Cloudinary: uses service (evidence: `js/cloudinary.js`)
- SEO generation workflow → Product model helpers: checks uniqueness (evidence: `js/seo-generator.js`)
- SEO generation workflow → SEO quality checks: uses fact prompts (evidence: `js/seo-generator.js`)
- Generation history → SEO generation workflow: restores record (evidence: `js/history.js`)
- SEO & performance audits → PageSpeed analysis: runs analysis (evidence: `js/audit.js`)
- PageSpeed analysis → Google PageSpeed Insights: analyzes pages (evidence: `README.md`)
- SEO & performance audits → Performance audit history: uses history (evidence: `js/audit.js`)
- Performance audit history → Firebase access layer: manages reports (evidence: `js/audit-history.js`)
- Storefront interface → Storefront commerce rules: imports (evidence: `storefront-demo/app.js`)
