# mizcausevic-dev/saas-help-center-geo-optimizer architecture

> Architecture diagram of the GitHub repository mizcausevic-dev/saas-help-center-geo-optimizer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mizcausevic-dev/saas-help-center-geo-optimizer
- Repository: https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer

## Overview

#### Purpose and principal workflow
This is a small FastAPI application for assessing SaaS help-center articles for generative-engine readiness and presenting prioritized content fixes. A browser or API client initiates the workflow by requesting a page or API endpoint; Uvicorn serves the application, which loads the bundled help-center dataset, scores its articles, and returns a summary, queue, or article result.

#### Components

##### Web application and interfaces
- **Uvicorn ASGI server** — `null` (external): The documented local run starts Uvicorn from the application module to serve the FastAPI app.
- **FastAPI routes and service wiring** — `app/main.py`: Creates the app and service instance, exposes HTML pages and JSON summary, article, sample, and OpenAPI routes, and returns 404 for unknown article slugs.
- **Help-center presentation** — `app/render.py`: Builds the overview, prioritized queue, evidence, and API-summary HTML pages; the sampled renderers call the GEO service to obtain their data.

##### Scoring and source data
- **GEO scoring and aggregation** — `app/services/geo_service.py`: Loads articles, computes readiness dimensions and a blended GEO score, derives per-article fixes and priority, and assembles queue, article, summary, and sample-payload results.
- **Bundled help-center dataset** — `app/data/sample_help_center.json`: Supplies the sample articles and brand/platform metadata read by the GEO service.

##### External caller
- **Browser or API client** — `null` (external): Requests the application’s HTML pages or JSON endpoints; the README documents local browser access.

#### Relationships
- **Browser or API client -> Uvicorn ASGI server**: Sends HTTP requests to the locally hosted application; the README documents the local URLs and run command.
- **Uvicorn ASGI server -> FastAPI routes and service wiring**: Serves the `app.main:app` application; the module’s run block calls `uvicorn.run`.
- **FastAPI routes and service wiring -> Help-center presentation**: Calls the page renderers for the HTML routes.
- **FastAPI routes and service wiring -> GEO scoring and aggregation**: Calls the service for summary, queue, article lookup, and sample-payload API results.
- **Help-center presentation -> GEO scoring and aggregation**: Calls service methods to populate rendered pages, including overview metrics and queue data.
- **GEO scoring and aggregation -> Bundled help-center dataset**: Reads and parses the JSON source file when loading article data.
- **Browser or API client -> FastAPI routes and service wiring**: Requests the documented pages and API endpoints; the app’s route definitions handle those requests.

#### Coverage limits
The render module excerpt omits portions of the queue and evidence renderers, so their exact data-selection details are not established. The README describes a Zendesk-style export, but the sampled code shows only the bundled JSON source; no external help-center connector or persistent state is evidenced.

Main entry points: [`app/main.py`](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/main.py) (FastAPI routes), [`app/services/geo_service.py`](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/services/geo_service.py) (GEO scoring service), [`app/render.py`](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/render.py) (Help-center presentation), [`app/data/sample_help_center.json`](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/data/sample_help_center.json) (Help-center dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external_access["External access"]
  node_client(("Browser or API client<br/>HTTP client"))
  node_uvicorn["Uvicorn ASGI server"]
end

subgraph group_web_application["Web application"]
  node_routes["FastAPI routes<br/>FastAPI app"]
  node_render["Help-center presentation<br/>HTML renderers"]
end

subgraph group_scoring_data["Scoring and data"]
  node_geo_service["GEO scoring service<br/>[geo_service.py]"]
  node_dataset["Help-center dataset<br/>JSON source"]
end

node_client -->|"Sends HTTP requests"| node_uvicorn
node_uvicorn -->|"Serves app"| node_routes
node_routes -->|"Calls renderers"| node_render
node_routes -->|"Requests results"| node_geo_service
node_render -->|"Gets page data"| node_geo_service
node_geo_service -->|"Reads JSON"| node_dataset
node_client -->|"Requests pages and APIs"| node_routes

click node_routes "https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/main.py"
click node_render "https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/render.py"
click node_geo_service "https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/services/geo_service.py"
click node_dataset "https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/data/sample_help_center.json"

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_client,node_uvicorn toneBlue
class node_routes,node_render toneAmber
class node_geo_service,node_dataset toneMint
```

## Components

### External access

- **Browser or API client**: HTTP client
- **Uvicorn ASGI server**: ASGI server

### Web application

- [FastAPI routes](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/main.py): FastAPI app · `app/main.py`
- [Help-center presentation](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/render.py): HTML renderers · `app/render.py`

### Scoring and data

- [GEO scoring service](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/services/geo_service.py): Scoring service · `app/services/geo_service.py`
- [Help-center dataset](https://github.com/mizcausevic-dev/saas-help-center-geo-optimizer/blob/main/app/data/sample_help_center.json): JSON source · `app/data/sample_help_center.json`

## Connections

- Browser or API client → Uvicorn ASGI server: Sends HTTP requests
- Uvicorn ASGI server → FastAPI routes: Serves app
- FastAPI routes → Help-center presentation: Calls renderers
- FastAPI routes → GEO scoring service: Requests results
- Help-center presentation → GEO scoring service: Gets page data
- GEO scoring service → Help-center dataset: Reads JSON
- Browser or API client → FastAPI routes: Requests pages and APIs