# yaojingang/georank architecture

> Architecture diagram of the GitHub repository yaojingang/georank, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yaojingang/georank
- Repository: https://github.com/yaojingang/georank

## Overview

GEOrank is a self-hosted GEO workbench. Its user workflow runs from discovering company and expert resources, through website diagnosis and AI-assisted Q&A, to actionable plans and reusable keyword, structured-data, and knowledge assets. Next.js web and admin apps use a shared API SDK to reach a FastAPI backend; backend services coordinate AI and persistence. The README documents capabilities not represented by sampled source, so those are shown at subsystem level. Some links are documented workflows rather than inspected call chains.

Main entry points: [`apps/web`](https://github.com/yaojingang/georank/tree/main/apps/web) (Web Workbench), [`backend/app/main.py`](https://github.com/yaojingang/georank/blob/main/backend/app/main.py) (FastAPI Application), [`apps/admin/components`](https://github.com/yaojingang/georank/tree/main/apps/admin/components) (Admin Console), [`backend/app/api/routes/companies.py`](https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/companies.py) (Company Directory API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User Experience"]
  node_web["Web Workbench"]
  node_discovery["Directories and Tutorials"]
  node_tools["GEO Tools<br/>[page.tsx]"]
  node_authui["Sign-in and Account<br/>[auth-form.tsx]"]
  node_admin["Admin Console"]
end

subgraph group_api["API and Domain"]
  node_apiapp["FastAPI Application<br/>[main.py]"]
  node_companyapi["Company Directory API<br/>[companies.py]"]
end

subgraph group_intelligence["AI and Analysis"]
  node_diagnostics["Website Diagnostics<br/>[diagnostics.py]"]
  node_qa["AI Q&amp;A<br/>[ai_client.py]"]
  node_solutions["GEO Action Plans<br/>[solutions.py]"]
  node_keywords["Keyword Expansion<br/>[keywords.py]"]
  node_ingest["Company Ingestion<br/>[company_ingest.py]"]
end

subgraph group_assets["Content and State"]
  node_experts["Expert Channel<br/>[experts.py]"]
  node_content["Content and Homepage<br/>[homepage_assets.py]"]
  node_settings["Runtime Settings"]
end

subgraph group_platform["Shared Platform"]
  node_sdk["API SDK<br/>[client.ts]"]
  node_db[("Relational Database<br/>[database.py]")]
  node_vector[("Vector and Graph Stores<br/>[vector_store.py]")]
  node_objectstore[("Object Storage<br/>[storage.py]")]
end

node_visitor(("GEO User"))
node_provider{{"Model Provider"}}

node_visitor -->|"uses"| node_web
node_web -->|"browses"| node_discovery
node_web -->|"submits site"| node_diagnostics
node_web -->|"asks questions"| node_qa
node_web -->|"requests plans"| node_solutions
node_web -->|"expands terms"| node_keywords
node_web -->|"uses tools"| node_tools
node_web -->|"authenticates"| node_authui
node_visitor -->|"administers"| node_admin
node_admin -->|"calls"| node_sdk
node_web -->|"calls"| node_sdk
node_sdk -.->|"sends API requests"| node_apiapp
node_apiapp -->|"mounts routes"| node_companyapi
node_apiapp -->|"mounts routes"| node_diagnostics
node_apiapp -->|"mounts routes"| node_solutions
node_apiapp -->|"mounts routes"| node_experts
node_apiapp -->|"mounts routes"| node_keywords
node_apiapp -->|"serves homepage"| node_content
node_companyapi -.->|"plans ingestion"| node_ingest
node_qa -->|"requests generation"| node_provider
node_diagnostics -.->|"stores reports"| node_db
node_solutions -.->|"stores plans"| node_db
node_companyapi -.->|"reads and writes"| node_db
node_qa -->|"retrieves context"| node_vector
node_ingest -.->|"builds knowledge assets"| node_vector
node_settings -->|"reads and writes"| node_db
node_content -.->|"stores assets"| node_objectstore
node_admin -->|"manages configuration"| node_settings
node_admin -->|"manages directory"| node_companyapi

click node_web "https://github.com/yaojingang/georank/tree/main/apps/web"
click node_discovery "https://github.com/yaojingang/georank/tree/main/backend/app/web"
click node_tools "https://github.com/yaojingang/georank/blob/main/apps/web/app/%5Blocale%5D/tools/page.tsx"
click node_authui "https://github.com/yaojingang/georank/blob/main/apps/web/components/auth/auth-form.tsx"
click node_admin "https://github.com/yaojingang/georank/tree/main/apps/admin/components"
click node_sdk "https://github.com/yaojingang/georank/blob/main/packages/api-sdk/src/client.ts"
click node_apiapp "https://github.com/yaojingang/georank/blob/main/backend/app/main.py"
click node_companyapi "https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/companies.py"
click node_diagnostics "https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/diagnostics.py"
click node_qa "https://github.com/yaojingang/georank/blob/main/backend/app/services/ai_client.py"
click node_solutions "https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/solutions.py"
click node_keywords "https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/keywords.py"
click node_ingest "https://github.com/yaojingang/georank/blob/main/backend/app/services/company_ingest.py"
click node_experts "https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/experts.py"
click node_content "https://github.com/yaojingang/georank/blob/main/backend/app/services/homepage_assets.py"
click node_settings "https://github.com/yaojingang/georank/blob/main/backend/app/services/runtime_settings.py"
click node_db "https://github.com/yaojingang/georank/blob/main/backend/app/core/database.py"
click node_vector "https://github.com/yaojingang/georank/blob/main/backend/app/services/vector_store.py"
click node_objectstore "https://github.com/yaojingang/georank/blob/main/backend/app/services/storage.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_web,node_discovery,node_tools,node_authui,node_admin,node_visitor toneBlue
class node_apiapp,node_companyapi toneAmber
class node_diagnostics,node_qa,node_solutions,node_keywords,node_ingest toneMint
class node_experts,node_content,node_settings toneRose
class node_sdk,node_db,node_vector,node_objectstore,node_provider toneIndigo
```

## Components

### User Experience

- [Web Workbench](https://github.com/yaojingang/georank/tree/main/apps/web): `apps/web`
- [Directories and Tutorials](https://github.com/yaojingang/georank/tree/main/backend/app/web): `backend/app/web`
- [GEO Tools](https://github.com/yaojingang/georank/blob/main/apps/web/app/%5Blocale%5D/tools/page.tsx): `apps/web/app/[locale]/tools/page.tsx`
- [Sign-in and Account](https://github.com/yaojingang/georank/blob/main/apps/web/components/auth/auth-form.tsx): `apps/web/components/auth/auth-form.tsx`
- [Admin Console](https://github.com/yaojingang/georank/tree/main/apps/admin/components): `apps/admin/components`

### API and Domain

- [FastAPI Application](https://github.com/yaojingang/georank/blob/main/backend/app/main.py): `backend/app/main.py`
- [Company Directory API](https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/companies.py): `backend/app/api/routes/companies.py`

### AI and Analysis

- [Website Diagnostics](https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/diagnostics.py): `backend/app/api/routes/diagnostics.py`
- [AI Q&A](https://github.com/yaojingang/georank/blob/main/backend/app/services/ai_client.py): `backend/app/services/ai_client.py`
- [GEO Action Plans](https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/solutions.py): `backend/app/api/routes/solutions.py`
- [Keyword Expansion](https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/keywords.py): `backend/app/api/routes/keywords.py`
- [Company Ingestion](https://github.com/yaojingang/georank/blob/main/backend/app/services/company_ingest.py): `backend/app/services/company_ingest.py`

### Content and State

- [Expert Channel](https://github.com/yaojingang/georank/blob/main/backend/app/api/routes/experts.py): `backend/app/api/routes/experts.py`
- [Content and Homepage](https://github.com/yaojingang/georank/blob/main/backend/app/services/homepage_assets.py): `backend/app/services/homepage_assets.py`
- [Runtime Settings](https://github.com/yaojingang/georank/blob/main/backend/app/services/runtime_settings.py): `backend/app/services/runtime_settings.py`

### Shared Platform

- [API SDK](https://github.com/yaojingang/georank/blob/main/packages/api-sdk/src/client.ts): `packages/api-sdk/src/client.ts`
- [Relational Database](https://github.com/yaojingang/georank/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Vector and Graph Stores](https://github.com/yaojingang/georank/blob/main/backend/app/services/vector_store.py): `backend/app/services/vector_store.py`
- [Object Storage](https://github.com/yaojingang/georank/blob/main/backend/app/services/storage.py): `backend/app/services/storage.py`

### Other components

- **GEO User**
- **Model Provider**

## Connections

- GEO User → Web Workbench: uses (evidence: `README.md`)
- Web Workbench → Directories and Tutorials: browses (evidence: `README.md`)
- Web Workbench → Website Diagnostics: submits site (evidence: `README.md`)
- Web Workbench → AI Q&A: asks questions (evidence: `README.md`)
- Web Workbench → GEO Action Plans: requests plans (evidence: `README.md`)
- Web Workbench → Keyword Expansion: expands terms (evidence: `README.md`)
- Web Workbench → GEO Tools: uses tools (evidence: `README.md`)
- Web Workbench → Sign-in and Account: authenticates (evidence: `README.md`)
- GEO User → Admin Console: administers (evidence: `README.md`)
- Admin Console → API SDK: calls (evidence: `apps/admin/components/companies/admin-companies.tsx`)
- Web Workbench → API SDK: calls (evidence: `apps/web/components/auth/auth-form.tsx`)
- API SDK → FastAPI Application: sends API requests
- FastAPI Application → Company Directory API: mounts routes
- FastAPI Application → Website Diagnostics: mounts routes
- FastAPI Application → GEO Action Plans: mounts routes
- FastAPI Application → Expert Channel: mounts routes
- FastAPI Application → Keyword Expansion: mounts routes
- FastAPI Application → Content and Homepage: serves homepage (evidence: `backend/app/main.py`)
- Company Directory API → Company Ingestion: plans ingestion
- AI Q&A → Model Provider: requests generation (evidence: `README.md`)
- Website Diagnostics → Relational Database: stores reports
- GEO Action Plans → Relational Database: stores plans
- Company Directory API → Relational Database: reads and writes
- AI Q&A → Vector and Graph Stores: retrieves context (evidence: `backend/app/services/ai_client.py`)
- Company Ingestion → Vector and Graph Stores: builds knowledge assets
- Runtime Settings → Relational Database: reads and writes (evidence: `backend/app/services/runtime_settings.py`)
- Content and Homepage → Object Storage: stores assets
- Admin Console → Runtime Settings: manages configuration (evidence: `README.md`)
- Admin Console → Company Directory API: manages directory (evidence: `README.md`)