# malsmadi80/geo-seo-claude architecture

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

- Interactive diagram: https://gitdiagram.com/malsmadi80/geo-seo-claude
- Repository: https://github.com/malsmadi80/geo-seo-claude

## Overview

This repository is a Claude Code skill suite for GEO-first website optimization, with Python utilities and a lightweight prospect CRM. The main workflow starts with a user command, routes through the GEO skill, discovers site information, runs specialized audit analyses, synthesizes findings, and produces reports. Separate command branches cover citability, crawler access, llms.txt, brand visibility, platform optimization, schema, technical SEO, and content. CRM, proposal, and comparison capabilities are documented, but their skill implementations were not sampled; their links are therefore limited to documented relationships. Analysis and routing links follow the README; sampled utility behavior is shown where visible.

Main entry points: [`agents`](https://github.com/malsmadi80/geo-seo-claude/tree/main/agents) (Parallel Subagents), [`skills/geo-audit/SKILL.md`](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-audit/SKILL.md) (Full Audit), [`geo/SKILL.md`](https://github.com/malsmadi80/geo-seo-claude/blob/main/geo/SKILL.md) (GEO Command Router), [`skills/geo-prospect/SKILL.md`](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-prospect/SKILL.md) (Prospect Pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Command Orchestration"]
  node_geo["GEO Command Router<br/>[SKILL.md]"]
  node_audit["Full Audit<br/>[SKILL.md]"]
end

subgraph group_analysis["Site Analysis"]
  node_discovery["Site Discovery<br/>[fetch_page.py]"]
  node_agents["Parallel Subagents"]
  node_citability["Citability Analysis"]
  node_crawler["Crawler Access<br/>[SKILL.md]"]
  node_brand["Brand Mentions<br/>[brand_scanner.py]"]
  node_llmstxt["llms.txt Tools"]
  node_platforms["Platform Optimization<br/>[SKILL.md]"]
  node_technical["Technical SEO<br/>[SKILL.md]"]
  node_content["Content &amp; E-E-A-T<br/>[SKILL.md]"]
  node_schema["Structured Data"]
end

subgraph group_deliverables["Reports &amp; Guidance"]
  node_synthesis["Score Synthesis<br/>[SKILL.md]"]
  node_markdown_report["Markdown Reports<br/>[SKILL.md]"]
  node_pdf_report["PDF Reports"]
end

subgraph group_operations["Client Operations"]
  node_prospect["Prospect Pipeline<br/>[SKILL.md]"]
  node_crm_ui["CRM Dashboard<br/>[app.py]"]
  node_crm_cli["CRM CLI<br/>[crm_dashboard.py]"]
  node_proposal["Proposals<br/>[SKILL.md]"]
  node_compare["Progress Comparison<br/>[SKILL.md]"]
  node_prospect_store[("Prospect Data")]
end

node_user(("User"))

node_user -->|"runs command"| node_geo
node_geo -->|"routes audit"| node_audit
node_audit -->|"discovers site"| node_discovery
node_audit -->|"launches parallel"| node_agents
node_agents -->|"analyzes citations"| node_citability
node_agents -->|"checks access"| node_crawler
node_agents -->|"checks mentions"| node_brand
node_agents -->|"analyzes guidance"| node_llmstxt
node_agents -->|"assesses readiness"| node_platforms
node_agents -->|"audits foundations"| node_technical
node_agents -->|"assesses quality"| node_content
node_agents -->|"analyzes markup"| node_schema
node_audit -->|"aggregates scores"| node_synthesis
node_synthesis -->|"generates findings"| node_markdown_report
node_user -->|"requests score"| node_citability
node_user -->|"requests check"| node_crawler
node_user -->|"requests analysis"| node_llmstxt
node_user -->|"requests scan"| node_brand
node_user -->|"requests tuning"| node_platforms
node_user -->|"requests audit"| node_technical
node_user -->|"requests review"| node_content
node_user -->|"requests analysis"| node_schema
node_user -->|"requests report"| node_markdown_report
node_user -->|"requests PDF"| node_pdf_report
node_user -->|"manages prospects"| node_prospect
node_user -->|"requests proposal"| node_proposal
node_user -->|"requests comparison"| node_compare
node_prospect -->|"stores pipeline"| node_prospect_store
node_proposal -->|"stores proposals"| node_prospect_store
node_compare -->|"stores reports"| node_prospect_store
node_crm_ui -->|"reads and writes"| node_prospect_store
node_crm_cli -->|"reads pipeline"| node_prospect_store

click node_geo "https://github.com/malsmadi80/geo-seo-claude/blob/main/geo/SKILL.md"
click node_audit "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-audit/SKILL.md"
click node_discovery "https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/fetch_page.py"
click node_agents "https://github.com/malsmadi80/geo-seo-claude/tree/main/agents"
click node_citability "https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/citability_scorer.py"
click node_crawler "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-crawlers/SKILL.md"
click node_brand "https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/brand_scanner.py"
click node_llmstxt "https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/llmstxt_generator.py"
click node_platforms "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-platform-optimizer/SKILL.md"
click node_technical "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-technical/SKILL.md"
click node_content "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-content/SKILL.md"
click node_schema "https://github.com/malsmadi80/geo-seo-claude/tree/main/schema"
click node_synthesis "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-audit/SKILL.md"
click node_markdown_report "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-report/SKILL.md"
click node_pdf_report "https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/generate_pdf_report.py"
click node_prospect "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-prospect/SKILL.md"
click node_crm_ui "https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/webapp/app.py"
click node_crm_cli "https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/crm_dashboard.py"
click node_proposal "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-proposal/SKILL.md"
click node_compare "https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-compare/SKILL.md"

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_geo,node_audit,node_user toneBlue
class node_discovery,node_agents,node_citability,node_crawler,node_brand,node_llmstxt,node_platforms,node_technical,node_content,node_schema toneAmber
class node_synthesis,node_markdown_report,node_pdf_report toneMint
class node_prospect,node_crm_ui,node_crm_cli,node_proposal,node_compare,node_prospect_store toneRose
```

## Components

### Command Orchestration

- [GEO Command Router](https://github.com/malsmadi80/geo-seo-claude/blob/main/geo/SKILL.md): `geo/SKILL.md`
- [Full Audit](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-audit/SKILL.md): `skills/geo-audit/SKILL.md`

### Site Analysis

- [Site Discovery](https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/fetch_page.py): `scripts/fetch_page.py`
- [Parallel Subagents](https://github.com/malsmadi80/geo-seo-claude/tree/main/agents): `agents`
- [Citability Analysis](https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/citability_scorer.py): `scripts/citability_scorer.py`
- [Crawler Access](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-crawlers/SKILL.md): `skills/geo-crawlers/SKILL.md`
- [Brand Mentions](https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/brand_scanner.py): `scripts/brand_scanner.py`
- [llms.txt Tools](https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/llmstxt_generator.py): `scripts/llmstxt_generator.py`
- [Platform Optimization](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-platform-optimizer/SKILL.md): `skills/geo-platform-optimizer/SKILL.md`
- [Technical SEO](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-technical/SKILL.md): `skills/geo-technical/SKILL.md`
- [Content & E-E-A-T](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-content/SKILL.md): `skills/geo-content/SKILL.md`
- [Structured Data](https://github.com/malsmadi80/geo-seo-claude/tree/main/schema): `schema`

### Reports & Guidance

- [Score Synthesis](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-audit/SKILL.md): `skills/geo-audit/SKILL.md`
- [Markdown Reports](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-report/SKILL.md): `skills/geo-report/SKILL.md`
- [PDF Reports](https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/generate_pdf_report.py): `scripts/generate_pdf_report.py`

### Client Operations

- [Prospect Pipeline](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-prospect/SKILL.md): `skills/geo-prospect/SKILL.md`
- [CRM Dashboard](https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/webapp/app.py): `scripts/webapp/app.py`
- [CRM CLI](https://github.com/malsmadi80/geo-seo-claude/blob/main/scripts/crm_dashboard.py): `scripts/crm_dashboard.py`
- [Proposals](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-proposal/SKILL.md): `skills/geo-proposal/SKILL.md`
- [Progress Comparison](https://github.com/malsmadi80/geo-seo-claude/blob/main/skills/geo-compare/SKILL.md): `skills/geo-compare/SKILL.md`
- **Prospect Data**

### Other components

- **User**

## Connections

- User → GEO Command Router: runs command (evidence: `README.md`)
- GEO Command Router → Full Audit: routes audit (evidence: `README.md`)
- Full Audit → Site Discovery: discovers site (evidence: `README.md`)
- Full Audit → Parallel Subagents: launches parallel (evidence: `README.md`)
- Parallel Subagents → Citability Analysis: analyzes citations (evidence: `README.md`)
- Parallel Subagents → Crawler Access: checks access (evidence: `README.md`)
- Parallel Subagents → Brand Mentions: checks mentions (evidence: `README.md`)
- Parallel Subagents → llms.txt Tools: analyzes guidance (evidence: `README.md`)
- Parallel Subagents → Platform Optimization: assesses readiness (evidence: `README.md`)
- Parallel Subagents → Technical SEO: audits foundations (evidence: `README.md`)
- Parallel Subagents → Content & E-E-A-T: assesses quality (evidence: `README.md`)
- Parallel Subagents → Structured Data: analyzes markup (evidence: `README.md`)
- Full Audit → Score Synthesis: aggregates scores (evidence: `README.md`)
- Score Synthesis → Markdown Reports: generates findings (evidence: `README.md`)
- User → Citability Analysis: requests score (evidence: `README.md`)
- User → Crawler Access: requests check (evidence: `README.md`)
- User → llms.txt Tools: requests analysis (evidence: `README.md`)
- User → Brand Mentions: requests scan (evidence: `README.md`)
- User → Platform Optimization: requests tuning (evidence: `README.md`)
- User → Technical SEO: requests audit (evidence: `README.md`)
- User → Content & E-E-A-T: requests review (evidence: `README.md`)
- User → Structured Data: requests analysis (evidence: `README.md`)
- User → Markdown Reports: requests report (evidence: `README.md`)
- User → PDF Reports: requests PDF (evidence: `README.md`)
- User → Prospect Pipeline: manages prospects (evidence: `README.md`)
- User → Proposals: requests proposal (evidence: `README.md`)
- User → Progress Comparison: requests comparison (evidence: `README.md`)
- Prospect Pipeline → Prospect Data: stores pipeline (evidence: `README.md`)
- Proposals → Prospect Data: stores proposals (evidence: `README.md`)
- Progress Comparison → Prospect Data: stores reports (evidence: `README.md`)
- CRM Dashboard → Prospect Data: reads and writes (evidence: `scripts/webapp/app.py`)
- CRM CLI → Prospect Data: reads pipeline (evidence: `README.md`)
