# gokuldevp/quotes-fastapi-scraper-llm architecture

> Architecture diagram of the GitHub repository gokuldevp/quotes-fastapi-scraper-llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gokuldevp/quotes-fastapi-scraper-llm
- Repository: https://github.com/gokuldevp/quotes-fastapi-scraper-llm

## Overview

This service exposes health, random-quote, and refresh endpoints. The principal workflow starts at `/refresh`: documented behavior launches Selenium, logs in, scrapes the first quotes page, formats the result through Gemini, and updates JSON storage and the in-memory cache; `/quote/random` serves cached data. Startup restores persisted quotes into cache. The README documents the scraper orchestration, but its implementation was not sampled, so those orchestration links reflect documentation rather than inspected calls.

Main entry points: [`app/main.py`](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/main.py) (FastAPI app), [`app/services/quote_scraper.py`](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/quote_scraper.py) (Quote scraper), [`app/services/login_service.py`](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/login_service.py) (Login service), [`app/pages/quotes_page.py`](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/pages/quotes_page.py) (Quotes page object)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and startup"]
  node_main["FastAPI app<br/>[main.py]"]
  node_health["Health endpoint<br/>[health.py]"]
  node_refresh["Refresh endpoint<br/>[refresh.py]"]
  node_random["Random quote endpoint<br/>[quote.py]"]
end

subgraph group_scrape["Scraping workflow"]
  node_scraper["Quote scraper<br/>[quote_scraper.py]"]
  node_browser["Browser manager<br/>[browser_manager.py]"]
  node_login["Login service<br/>[login_service.py]"]
  node_loginpage["Login page object<br/>[login_page.py]"]
  node_quotespage["Quotes page object<br/>[quotes_page.py]"]
  node_basepage["Base page object<br/>[base_page.py]"]
  node_ai["AI formatter<br/>[ai_services.py]"]
end

subgraph group_state["Quote state"]
  node_storage[("JSON storage<br/>[storage_service.py]")]
  node_cache["Quote cache<br/>[cache.py]"]
  node_quote_model["Quote response model<br/>[quote.py]"]
end

subgraph group_support["Configuration and reliability"]
  node_config["Configuration<br/>[config.py]"]
  node_exceptions["Login exceptions<br/>[exceptions.py]"]
  node_screenshot["Screenshot capture<br/>[screenshot.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_user(("API client"))
node_site{{"Quotes website"}}
node_gemini{{"Gemini API"}}

node_user -->|"sends requests"| node_main
node_main -->|"registers routes"| node_health
node_main -->|"registers routes"| node_refresh
node_main -->|"registers routes"| node_random
node_main -->|"loads quotes"| node_storage
node_main -->|"restores quotes"| node_cache
node_refresh -->|"runs scrape"| node_scraper
node_refresh -->|"logs failures"| node_logger
node_scraper -->|"manages browser"| node_browser
node_scraper -->|"authenticates"| node_login
node_scraper -->|"scrapes quotes"| node_quotespage
node_scraper -->|"saves quotes"| node_storage
node_scraper -->|"refreshes cache"| node_cache
node_browser -->|"reads settings"| node_config
node_browser -->|"opens browser"| node_site
node_login -->|"performs login"| node_loginpage
node_login -->|"reads credentials"| node_config
node_login -->|"catches errors"| node_exceptions
node_login -->|"captures failures"| node_screenshot
node_login -->|"logs attempts"| node_logger
node_loginpage -->|"uses base"| node_basepage
node_loginpage -->|"submits credentials"| node_site
node_quotespage -->|"uses base"| node_basepage
node_quotespage -->|"formats extracted data"| node_ai
node_quotespage -->|"reads quote page"| node_site
node_ai -->|"reads prompt settings"| node_config
node_ai -->|"requests formatting"| node_gemini
node_random -->|"selects cached quote"| node_cache
node_random -->|"returns response"| node_quote_model

click node_main "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/main.py"
click node_health "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/api/health.py"
click node_refresh "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/api/refresh.py"
click node_random "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/api/quote.py"
click node_scraper "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/quote_scraper.py"
click node_browser "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/browser_manager.py"
click node_login "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/login_service.py"
click node_loginpage "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/pages/login_page.py"
click node_quotespage "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/pages/quotes_page.py"
click node_basepage "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/pages/base_page.py"
click node_ai "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/ai_services.py"
click node_storage "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/storage_service.py"
click node_cache "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/cache.py"
click node_quote_model "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/models/quote.py"
click node_config "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/config.py"
click node_exceptions "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/exceptions.py"
click node_screenshot "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/screenshot.py"
click node_logger "https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/logger.py"

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_main,node_health,node_refresh,node_random,node_user toneBlue
class node_scraper,node_browser,node_login,node_loginpage,node_quotespage,node_basepage,node_ai toneAmber
class node_storage,node_cache,node_quote_model,node_gemini toneMint
class node_config,node_exceptions,node_screenshot,node_logger toneRose
class node_site toneIndigo
```

## Components

### API and startup

- [FastAPI app](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/main.py): `app/main.py`
- [Health endpoint](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/api/health.py): `app/api/health.py`
- [Refresh endpoint](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/api/refresh.py): `app/api/refresh.py`
- [Random quote endpoint](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/api/quote.py): `app/api/quote.py`

### Scraping workflow

- [Quote scraper](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/quote_scraper.py): `app/services/quote_scraper.py`
- [Browser manager](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/browser_manager.py): `app/services/browser_manager.py`
- [Login service](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/login_service.py): `app/services/login_service.py`
- [Login page object](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/pages/login_page.py): `app/pages/login_page.py`
- [Quotes page object](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/pages/quotes_page.py): `app/pages/quotes_page.py`
- [Base page object](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/pages/base_page.py): `app/pages/base_page.py`
- [AI formatter](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/ai_services.py): `app/services/ai_services.py`

### Quote state

- [JSON storage](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/services/storage_service.py): `app/services/storage_service.py`
- [Quote cache](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/cache.py): `app/core/cache.py`
- [Quote response model](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/models/quote.py): `app/models/quote.py`

### Configuration and reliability

- [Configuration](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/config.py): `app/core/config.py`
- [Login exceptions](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/exceptions.py): `app/core/exceptions.py`
- [Screenshot capture](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/screenshot.py): `app/core/screenshot.py`
- [Logging](https://github.com/gokuldevp/quotes-fastapi-scraper-llm/blob/main/app/core/logger.py): `app/core/logger.py`

### Other components

- **API client**
- **Quotes website**
- **Gemini API**

## Connections

- API client → FastAPI app: sends requests
- FastAPI app → Health endpoint: registers routes
- FastAPI app → Refresh endpoint: registers routes
- FastAPI app → Random quote endpoint: registers routes
- FastAPI app → JSON storage: loads quotes
- FastAPI app → Quote cache: restores quotes
- Refresh endpoint → Quote scraper: runs scrape
- Refresh endpoint → Logging: logs failures
- Quote scraper → Browser manager: manages browser
- Quote scraper → Login service: authenticates
- Quote scraper → Quotes page object: scrapes quotes
- Quote scraper → JSON storage: saves quotes
- Quote scraper → Quote cache: refreshes cache
- Browser manager → Configuration: reads settings
- Browser manager → Quotes website: opens browser
- Login service → Login page object: performs login
- Login service → Configuration: reads credentials
- Login service → Login exceptions: catches errors
- Login service → Screenshot capture: captures failures
- Login service → Logging: logs attempts
- Login page object → Base page object: uses base
- Login page object → Quotes website: submits credentials
- Quotes page object → Base page object: uses base
- Quotes page object → AI formatter: formats extracted data
- Quotes page object → Quotes website: reads quote page
- AI formatter → Configuration: reads prompt settings
- AI formatter → Gemini API: requests formatting
- Random quote endpoint → Quote cache: selects cached quote
- Random quote endpoint → Quote response model: returns response