# rossyanez/freecrawl-seo-tool architecture

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

- Interactive diagram: https://gitdiagram.com/rossyanez/freecrawl-seo-tool
- Repository: https://github.com/rossyanez/freecrawl-seo-tool

## Overview

FreeCrawl is a local-first desktop SEO crawler for large sites. A user configures and starts a crawl in the desktop UI; crawling fetches and parses pages, persists URL findings, and streams results for audit and analysis. The product also covers project management, exports, Google data, spelling, AI, logs, and agent-driven operation. The README documents these capabilities; the excerpts and source index support selected internal relationships, while unsampled implementation details are not asserted as verified calls.

Main entry points: [`packages/core/src/crawler.ts`](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/crawler.ts) (Crawler), [`apps/desktop/src/renderer/src/App.tsx`](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/App.tsx) (Desktop workspace), [`packages/db/src/project-db.ts`](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/db/src/project-db.ts) (Project database), [`apps/mcp-server/src/tools.ts`](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/mcp-server/src/tools.ts) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop experience"]
  node_app["Desktop workspace<br/>[App.tsx]"]
  node_state["UI state<br/>[store.ts]"]
  node_grid["URL results grid<br/>[UrlGridCanvas.tsx]"]
  node_auditviews["Audit views<br/>[SeoTab.tsx]"]
  node_logs["Log analysis<br/>[log-parser.ts]"]
end

subgraph group_crawl["Crawl and analysis"]
  node_crawler["Crawler<br/>[crawler.ts]"]
  node_http["HTTP and DNS<br/>[http-client.ts]"]
  node_html["Page parsing<br/>[html-parser.ts]"]
  node_parserworker["Parser worker<br/>[parser-worker.ts]"]
  node_seo["SEO checks<br/>[issue-catalog.ts]"]
  node_render["Browser rendering<br/>[render-fetcher.ts]"]
end

subgraph group_data["Projects and export"]
  node_db[("Project database<br/>[project-db.ts]")]
  node_migration["Schema migrations<br/>[migrations.ts]"]
  node_exports["Data and reports<br/>[tabular-export.ts]"]
  node_archive["Project archives<br/>[project-archive.ts]"]
end

subgraph group_integrations["Enrichment and agents"]
  node_google["Google integrations<br/>[google-oauth.ts]"]
  node_analytics["SEO data providers<br/>[seo-providers.ts]"]
  node_spell["Spelling checks<br/>[languagetool.ts]"]
  node_ai["AI assistance<br/>[ai-chat.ts]"]
  node_mcp["MCP tools<br/>[tools.ts]"]
  node_bridge["Desktop bridge<br/>[desktop-bridge.ts]"]
end

node_user(("SEO user"))
node_agent(("AI agent"))
node_googleapis{{"Google services"}}
node_languagetoolservice{{"LanguageTool service"}}
node_aiprovider{{"AI providers"}}

node_user -->|"uses"| node_app
node_app -->|"manages"| node_state
node_app -->|"shows results"| node_grid
node_app -->|"opens audits"| node_auditviews
node_user -->|"starts crawl"| node_crawler
node_crawler -.->|"fetches pages"| node_http
node_crawler -.->|"parses pages"| node_html
node_parserworker -->|"runs parser"| node_html
node_crawler -.->|"renders JavaScript"| node_render
node_crawler -.->|"checks pages"| node_seo
node_crawler -.->|"stores findings"| node_db
node_db -.->|"feeds results"| node_grid
node_user -->|"analyzes logs"| node_logs
node_user -->|"exports results"| node_exports
node_user -->|"saves project"| node_archive
node_user -->|"connects account"| node_google
node_google -.->|"fetches metrics"| node_analytics
node_analytics -.->|"queries services"| node_googleapis
node_user -->|"checks writing"| node_spell
node_spell -->|"checks language"| node_languagetoolservice
node_user -->|"runs prompts"| node_ai
node_ai -->|"requests completion"| node_aiprovider
node_agent -->|"calls tools"| node_mcp
node_mcp -->|"sends requests"| node_bridge
node_bridge -->|"controls crawl"| node_crawler
node_mcp -->|"reads results"| node_db
node_migration -.->|"defines schema"| node_db

click node_app "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/App.tsx"
click node_state "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/store.ts"
click node_grid "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/grid/UrlGridCanvas.tsx"
click node_auditviews "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/tabs/SeoTab.tsx"
click node_logs "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/log-parser.ts"
click node_crawler "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/crawler.ts"
click node_http "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/http-client.ts"
click node_html "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/html-parser.ts"
click node_parserworker "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/parser-worker.ts"
click node_seo "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/shared-types/src/issue-catalog.ts"
click node_render "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/render-fetcher.ts"
click node_db "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/db/src/project-db.ts"
click node_migration "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/db/src/migrations.ts"
click node_exports "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/tabular-export.ts"
click node_archive "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/project-archive.ts"
click node_google "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/google-oauth.ts"
click node_analytics "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/seo-providers.ts"
click node_spell "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/languagetool.ts"
click node_ai "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/ai-chat.ts"
click node_mcp "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/mcp-server/src/tools.ts"
click node_bridge "https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/mcp-server/src/desktop-bridge.ts"

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_app,node_state,node_grid,node_auditviews,node_logs,node_user toneBlue
class node_crawler,node_http,node_html,node_parserworker,node_seo,node_render toneAmber
class node_db,node_migration,node_exports,node_archive toneMint
class node_google,node_analytics,node_spell,node_ai,node_mcp,node_bridge toneRose
class node_agent,node_googleapis,node_languagetoolservice,node_aiprovider toneIndigo
```

## Components

### Desktop experience

- [Desktop workspace](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/App.tsx): `apps/desktop/src/renderer/src/App.tsx`
- [UI state](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/store.ts): `apps/desktop/src/renderer/src/store.ts`
- [URL results grid](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/grid/UrlGridCanvas.tsx): `apps/desktop/src/renderer/src/grid/UrlGridCanvas.tsx`
- [Audit views](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/renderer/src/tabs/SeoTab.tsx): `apps/desktop/src/renderer/src/tabs/SeoTab.tsx`
- [Log analysis](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/log-parser.ts): `packages/core/src/log-parser.ts`

### Crawl and analysis

- [Crawler](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/crawler.ts): `packages/core/src/crawler.ts`
- [HTTP and DNS](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/http-client.ts): `packages/core/src/http-client.ts`
- [Page parsing](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/html-parser.ts): `packages/core/src/html-parser.ts`
- [Parser worker](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/parser-worker.ts): `apps/desktop/src/main/parser-worker.ts`
- [SEO checks](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/shared-types/src/issue-catalog.ts): `packages/shared-types/src/issue-catalog.ts`
- [Browser rendering](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/render-fetcher.ts): `packages/core/src/render-fetcher.ts`

### Projects and export

- [Project database](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/db/src/project-db.ts): `packages/db/src/project-db.ts`
- [Schema migrations](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/db/src/migrations.ts): `packages/db/src/migrations.ts`
- [Data and reports](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/packages/core/src/tabular-export.ts): `packages/core/src/tabular-export.ts`
- [Project archives](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/project-archive.ts): `apps/desktop/src/main/project-archive.ts`

### Enrichment and agents

- [Google integrations](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/google-oauth.ts): `apps/desktop/src/main/google-oauth.ts`
- [SEO data providers](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/seo-providers.ts): `apps/desktop/src/main/seo-providers.ts`
- [Spelling checks](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/languagetool.ts): `apps/desktop/src/main/languagetool.ts`
- [AI assistance](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/desktop/src/main/ai-chat.ts): `apps/desktop/src/main/ai-chat.ts`
- [MCP tools](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/mcp-server/src/tools.ts): `apps/mcp-server/src/tools.ts`
- [Desktop bridge](https://github.com/rossyanez/freecrawl-seo-tool/blob/main/apps/mcp-server/src/desktop-bridge.ts): `apps/mcp-server/src/desktop-bridge.ts`

### Other components

- **SEO user**
- **AI agent**
- **Google services**
- **LanguageTool service**
- **AI providers**

## Connections

- SEO user → Desktop workspace: uses (evidence: `README.md`)
- Desktop workspace → UI state: manages (evidence: `apps/desktop/src/renderer/src/App.tsx`)
- Desktop workspace → URL results grid: shows results (evidence: `README.md`)
- Desktop workspace → Audit views: opens audits (evidence: `README.md`)
- SEO user → Crawler: starts crawl (evidence: `README.md`)
- Crawler → HTTP and DNS: fetches pages
- Crawler → Page parsing: parses pages
- Parser worker → Page parsing: runs parser (evidence: `apps/desktop/src/main/parser-worker.ts`)
- Crawler → Browser rendering: renders JavaScript
- Crawler → SEO checks: checks pages
- Crawler → Project database: stores findings
- Project database → URL results grid: feeds results
- SEO user → Log analysis: analyzes logs (evidence: `README.md`)
- SEO user → Data and reports: exports results (evidence: `README.md`)
- SEO user → Project archives: saves project (evidence: `README.md`)
- SEO user → Google integrations: connects account (evidence: `README.md`)
- Google integrations → SEO data providers: fetches metrics
- SEO data providers → Google services: queries services
- SEO user → Spelling checks: checks writing (evidence: `README.md`)
- Spelling checks → LanguageTool service: checks language (evidence: `README.md`)
- SEO user → AI assistance: runs prompts (evidence: `README.md`)
- AI assistance → AI providers: requests completion (evidence: `README.md`)
- AI agent → MCP tools: calls tools (evidence: `README.md`)
- MCP tools → Desktop bridge: sends requests (evidence: `apps/mcp-server/src/tools.ts`)
- Desktop bridge → Crawler: controls crawl (evidence: `apps/mcp-server/src/desktop-bridge.ts`)
- MCP tools → Project database: reads results (evidence: `apps/mcp-server/src/tools.ts`)
- Schema migrations → Project database: defines schema (evidence: `packages/db/src/project-db.ts`)
