# dib59/seo architecture

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

- Interactive diagram: https://gitdiagram.com/dib59/seo
- Repository: https://github.com/dib59/seo

## Overview

1. **Overall shape**
   - This is a **desktop SEO analysis application** built as a **Tauri v2** shell with a **Next.js/React** frontend and a **Rust** backend.
   - The app runs locally, stores data in **SQLite**, and ships as native desktop bundles rather than a hosted web service.

2. **Frontend boundary**
   - The `src/` tree is the UI layer: `app/` contains the main routes and screens for **home**, **analysis**, **analysis details**, and **config/settings**.
   - `src/api/` and `src/hooks/` form the client-side data-access and state layer that talks to the Rust side through generated Tauri bindings.
   - `src/components/` and the `ui/` primitives provide the reusable design system and shell components used across the app.

3. **Backend boundary**
   - `src-tauri/src/` is the Rust application core. It is organized as a layered backend with:
     - `commands/` as the Tauri IPC façade,
     - `contexts/` for domain-centric modules,
     - `service/` for operational orchestration,
     - `repository/` for SQLite persistence,
     - `extractor/` and `checker/` for crawl/audit logic.
   - `src-tauri/src/main.rs` and `lifecycle/` boot the Tauri app and register shared state/services.

4. **Main business domains**
   - The backend is split into several domains: **analysis**, **AI**, **reporting**, **licensing**, **local model**, **tags**, and **extensions**.
   - Each domain has its own `domain/`, `services/`, and sometimes `factory/` modules, which suggests a deliberate DDD-style boundary rather than one large service layer.

5. **Analysis pipeline**
   - The core product flow is: a URL is submitted in the UI, the backend creates or updates an **analysis job**, then a crawler/discovery process enumerates pages and links.
   - The `service/processor/` modules (`crawler`, `analyzer`, `reporter`, `queue`, `page_queue`, `canceler`) indicate a multi-stage pipeline with job control, progress reporting, and cancellation.
   - Results are persisted through SQLite repositories for jobs, pages, links, issues, queues, and analysis outputs, then read back by the analysis dashboard and detail pages.

6. **Crawl, extraction, and SEO checks**
   - `extractor/` handles page data extraction, sitemap discovery, and selector-based data capture.
   - `checker/builtin/` contains built-in audits such as **content** and **SEO** checks, while `checker/custom.rs` supports user-defined checks.
   - This creates a boundary between raw page fetching/extraction and the higher-level issue generation used in the UI.

7. **AI and local inference**
   - AI features are not a thin add-on; they are a separate domain with dedicated factory/service code and tests.
   - The app supports **Gemini-backed insights** and also a **local model** subsystem with downloader/inference services, implying two AI execution paths: cloud API and local inference.
   - The UI exposes this through configuration screens for personas, prompts, and AI settings.

8. **Reporting and templates**
   - Reporting is another major subsystem: `contexts/report/` contains **pattern matching**, **brief generation**, **report templates**, and a template engine.
   - The UI configuration area includes report pattern and template editors, which map to backend repositories and migrations for persistent customization.
   - Output formats described in the README—PDF, CSV, and text—are likely produced from the same persisted analysis/result model.

9. **Persistence model**
   - SQLite is the authoritative local store for the application’s state: jobs, pages, settings, AI insights, templates, report patterns, licensing data, and queue state.
   - The many migrations show a mature schema that evolved over time, including job lifecycle changes, page queueing, SEO flags, licensing fields, extension tables, and HTML caching.
   - `src-tauri/.sqlx/` indicates SQLx offline query verification is part of the build/test architecture.

10. **Licensing and feature gating**
   - Licensing is a dedicated backend concern with its own domain, service, repository support, and UI screens for activation and plan status.
   - This means some features are likely gated or enabled based on entitlement state, not just user preferences.

11. **Extensions, tags, and customization**
   - The presence of `extension` modules, custom rules migrations, tags registry/model, and multiple config editors shows the product is designed for **user extensibility**.
   - Instead of hardcoding every audit or reporting rule, the system persists configurable extractors, checks, tags, patterns, and templates and wires them into the analysis/reporting pipeline.

12. **Native runtime integrations**
   - The repo includes a packaged `lighthouse-runner` binary and platform-specific assets/icons, showing that the app depends on external native tooling for performance-related page analysis.
   - Tauri capabilities and generated bindings form the runtime bridge between the frontend and native backend, while the app remains fully local.

13. **Testing and boundary enforcement**
   - The backend has unit, integration, and end-to-end tests, plus trybuild tests that enforce architectural boundaries and privacy rules between modules.
   - The frontend has extensive component and hook tests, so the UI is structured around reusable stateful hooks and composable view components rather than monolithic screens.

14. **What an architecture diagram should emphasize**
   - Draw the system as a **local desktop client** with:
     - a React/Next UI layer,
     - a Tauri command bridge,
     - a Rust domain/service/repository backend,
     - SQLite as the shared persistence layer,
     - and separate external dependencies for **Gemini**, **local model inference**, and the **lighthouse-runner** binary.
   - The most important data flow is: **user input → analysis job → crawl/extract/check pipeline → persisted results → dashboard/reporting/exports**.

Main entry points: [`src-tauri/src/repository/sqlite`](https://github.com/dib59/seo/tree/main/src-tauri/src/repository/sqlite) (SQLite Repos), [`src-tauri/src/commands`](https://github.com/dib59/seo/tree/main/src-tauri/src/commands) (Commands), [`src/api`](https://github.com/dib59/seo/tree/main/src/api) (API Layer), [`src-tauri/src/service/processor`](https://github.com/dib59/seo/tree/main/src-tauri/src/service/processor) (Processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_ui_shell["App Shell<br/>Next.js UI"]
  node_home_screen["Home<br/>landing screen<br/>[page.tsx]"]
  node_analysis_dashboard["Analysis<br/>results screen"]
  node_page_detail_view["Page Details<br/>detail screen"]
  node_config_screen["Config<br/>settings screen"]
  node_client_api["API Layer<br/>Tauri client"]
  node_state_hooks["Hooks<br/>state layer"]
  node_design_system["UI Primitives<br/>component library"]
end

subgraph group_backend["Rust Backend"]
  node_tauri_main["Tauri Main<br/>desktop bootstrap<br/>[main.rs]"]
  node_lifecycle["Lifecycle<br/>app state"]
  node_commands["Commands<br/>IPC facade"]
  node_analysis_context["Analysis Core<br/>domain context"]
  node_processor["Processor<br/>pipeline engine"]
  node_extractor["Extractor<br/>crawl extraction"]
  node_checker["Checker<br/>audit rules"]
  node_report_context["Reporting"]
  node_ai_context["AI"]
  node_local_model["Local Model<br/>inference context"]
  node_licensing["Licensing<br/>entitlement context"]
  node_tags_ext["Tags & Ext<br/>customization"]
end

subgraph group_storage["Persistence"]
  node_repositories[("SQLite Repos<br/>persistence layer")]
  node_migrations["Migrations<br/>schema evolution"]
  node_sqlx_cache["SQLx Cache<br/>query metadata<br/>[.sqlx]"]
end

subgraph group_native["Native Tools"]
  node_lighthouse_runner["Lighthouse Runner<br/>native binary"]
end

node_home_screen -->|"submit URL"| node_client_api
node_analysis_dashboard -->|"load results"| node_client_api
node_page_detail_view -->|"load page"| node_client_api
node_config_screen -->|"save settings"| node_client_api
node_client_api -->|"invoke IPC"| node_commands
node_state_hooks -->|"wrap data"| node_client_api
node_ui_shell -->|"route"| node_home_screen
node_ui_shell -->|"route"| node_analysis_dashboard
node_ui_shell -->|"route"| node_page_detail_view
node_ui_shell -->|"route"| node_config_screen
node_design_system -->|"render"| node_ui_shell
node_tauri_main -->|"boot"| node_lifecycle
node_lifecycle -->|"register"| node_commands
node_commands -->|"analysis ops"| node_analysis_context
node_commands -->|"report ops"| node_report_context
node_commands -->|"ai ops"| node_ai_context
node_commands -->|"license ops"| node_licensing
node_commands -->|"model ops"| node_local_model
node_commands -->|"ext ops"| node_tags_ext
node_analysis_context -->|"drive pipeline"| node_processor
node_processor -->|"crawl"| node_extractor
node_processor -->|"audit"| node_checker
node_processor -->|"summarize"| node_report_context
node_extractor -->|"persist pages"| node_repositories
node_checker -->|"persist issues"| node_repositories
node_report_context -->|"load patterns"| node_repositories
node_ai_context -->|"store insights"| node_repositories
node_local_model -->|"store model state"| node_repositories
node_licensing -->|"store license"| node_repositories
node_tags_ext -->|"store customization"| node_repositories
node_repositories -->|"evolve schema"| node_migrations
node_repositories -->|"verify queries"| node_sqlx_cache
node_analysis_context -->|"job data"| node_repositories
node_processor -->|"run performance"| node_lighthouse_runner

click node_ui_shell "https://github.com/dib59/seo/tree/main/src/app"
click node_home_screen "https://github.com/dib59/seo/blob/main/src/app/page.tsx"
click node_analysis_dashboard "https://github.com/dib59/seo/tree/main/src/app/analysis"
click node_page_detail_view "https://github.com/dib59/seo/tree/main/src/app/analysis/details"
click node_config_screen "https://github.com/dib59/seo/tree/main/src/app/config"
click node_client_api "https://github.com/dib59/seo/tree/main/src/api"
click node_state_hooks "https://github.com/dib59/seo/tree/main/src/hooks"
click node_design_system "https://github.com/dib59/seo/tree/main/src/components/ui"
click node_tauri_main "https://github.com/dib59/seo/blob/main/src-tauri/src/main.rs"
click node_lifecycle "https://github.com/dib59/seo/tree/main/src-tauri/src/lifecycle"
click node_commands "https://github.com/dib59/seo/tree/main/src-tauri/src/commands"
click node_analysis_context "https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/analysis"
click node_processor "https://github.com/dib59/seo/tree/main/src-tauri/src/service/processor"
click node_extractor "https://github.com/dib59/seo/tree/main/src-tauri/src/extractor"
click node_checker "https://github.com/dib59/seo/tree/main/src-tauri/src/checker"
click node_report_context "https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/report"
click node_ai_context "https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/ai"
click node_local_model "https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/local_model"
click node_licensing "https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/licensing"
click node_tags_ext "https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/tags"
click node_repositories "https://github.com/dib59/seo/tree/main/src-tauri/src/repository/sqlite"
click node_migrations "https://github.com/dib59/seo/tree/main/src-tauri/migrations"
click node_sqlx_cache "https://github.com/dib59/seo/blob/main/src-tauri/.sqlx"
click node_lighthouse_runner "https://github.com/dib59/seo/tree/main/src-tauri/binaries/lighthouse-runner"

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_ui_shell,node_home_screen,node_analysis_dashboard,node_page_detail_view,node_config_screen,node_client_api,node_state_hooks,node_design_system toneBlue
class node_tauri_main,node_lifecycle,node_commands,node_analysis_context,node_processor,node_extractor,node_checker,node_report_context,node_ai_context,node_local_model,node_licensing,node_tags_ext toneAmber
class node_repositories,node_migrations,node_sqlx_cache toneMint
class node_lighthouse_runner toneRose
```

## Components

### Frontend

Next.js/React desktop UI layer

- [App Shell](https://github.com/dib59/seo/tree/main/src/app): Next.js UI · Global layout, routes, and desktop shell · `src/app`
- [Home](https://github.com/dib59/seo/blob/main/src/app/page.tsx): landing screen · Entry screen for starting analysis jobs · `src/app/page.tsx`
- [Analysis](https://github.com/dib59/seo/tree/main/src/app/analysis): results screen · Dashboard, graphs, exports, and issue overview · `src/app/analysis`
- [Page Details](https://github.com/dib59/seo/tree/main/src/app/analysis/details): detail screen · Per-page SEO, links, metadata, and performance view · `src/app/analysis/details`
- [Config](https://github.com/dib59/seo/tree/main/src/app/config): settings screen · General settings, AI, licensing, templates, tags, and custom rules · `src/app/config`
- [API Layer](https://github.com/dib59/seo/tree/main/src/api): Tauri client · Frontend data-access wrapper around generated bindings · `src/api`
- [Hooks](https://github.com/dib59/seo/tree/main/src/hooks): state layer · Client-side CRUD, mutations, analysis state, and permissions · `src/hooks`
- [UI Primitives](https://github.com/dib59/seo/tree/main/src/components/ui): component library · Reusable shell, form, table, and feedback components · `src/components/ui`

### Rust Backend

Tauri application core and domain services

- [Tauri Main](https://github.com/dib59/seo/blob/main/src-tauri/src/main.rs): desktop bootstrap · Starts the native app and wires shared state · `src-tauri/src/main.rs`
- [Lifecycle](https://github.com/dib59/seo/tree/main/src-tauri/src/lifecycle): app state · Application state and startup wiring · `src-tauri/src/lifecycle`
- [Commands](https://github.com/dib59/seo/tree/main/src-tauri/src/commands): IPC facade · Tauri command entrypoints exposed to the UI · `src-tauri/src/commands`
- [Analysis Core](https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/analysis): domain context · Job lifecycle, pages, links, issues, and progress · `src-tauri/src/contexts/analysis`
- [Processor](https://github.com/dib59/seo/tree/main/src-tauri/src/service/processor): pipeline engine · Crawler, analyzer, reporter, queue, and cancelation orchestration · `src-tauri/src/service/processor`
- [Extractor](https://github.com/dib59/seo/tree/main/src-tauri/src/extractor): crawl extraction · Page extraction, sitemap discovery, and selector capture · `src-tauri/src/extractor`
- [Checker](https://github.com/dib59/seo/tree/main/src-tauri/src/checker): audit rules · Built-in and custom SEO/content checks · `src-tauri/src/checker`
- [Reporting](https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/report): reporting context · Pattern matching, brief generation, and template engine · `src-tauri/src/contexts/report`
- [AI](https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/ai): ai context · AI insights and local/cloud inference orchestration · `src-tauri/src/contexts/ai`
- [Local Model](https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/local_model): inference context · Model download and local inference support · `src-tauri/src/contexts/local_model`
- [Licensing](https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/licensing): entitlement context · License state, activation, and feature gating · `src-tauri/src/contexts/licensing`
- [Tags & Ext](https://github.com/dib59/seo/tree/main/src-tauri/src/contexts/tags): customization · Tag registry and extension boundary for configurable analysis · `src-tauri/src/contexts/tags`

### Persistence

Local SQLite schema and repositories

- [SQLite Repos](https://github.com/dib59/seo/tree/main/src-tauri/src/repository/sqlite): persistence layer · Job, page, link, issue, report, template, settings, and AI storage · `src-tauri/src/repository/sqlite`
- [Migrations](https://github.com/dib59/seo/tree/main/src-tauri/migrations): schema evolution · Versioned SQLite schema changes for jobs, queues, reports, licensing, and customization · `src-tauri/migrations`
- [SQLx Cache](https://github.com/dib59/seo/blob/main/src-tauri/.sqlx): query metadata · Offline query verification metadata · `src-tauri/.sqlx`

### Native Tools

Bundled external binaries and platform assets

- [Lighthouse Runner](https://github.com/dib59/seo/tree/main/src-tauri/binaries/lighthouse-runner): native binary · Bundled external performance analysis executable · `src-tauri/binaries/lighthouse-runner`

## Connections

- Home → API Layer: submit URL · Starts a new analysis job through the client API
- Analysis → API Layer: load results · Reads jobs, pages, issues, and report data
- Page Details → API Layer: load page · Fetches detailed page analysis and extraction data
- Config → API Layer: save settings · Persists AI, licensing, templates, tags, and rules
- API Layer → Commands: invoke IPC · Frontend calls generated Tauri command bindings
- Hooks → API Layer: wrap data · Hooks coordinate query, mutation, and UI state
- App Shell → Home: route · Application landing route
- App Shell → Analysis: route · Analysis route
- App Shell → Page Details: route · Page detail route
- App Shell → Config: route · Configuration route
- UI Primitives → App Shell: render · Reusable primitives used by the shell and screens
- Tauri Main → Lifecycle: boot · Initializes shared application state
- Lifecycle → Commands: register · Exposes backend capabilities to the UI
- Commands → Analysis Core: analysis ops · Command façade delegates job and page operations
- Commands → Reporting: report ops · Command façade exposes reporting features
- Commands → AI: ai ops · Command façade exposes insights and model actions
- Commands → Licensing: license ops · Command façade manages activation and entitlement state
- Commands → Local Model: model ops · Command façade exposes local model controls
- Commands → Tags & Ext: ext ops · Command façade manages tags and extension-related config
- Analysis Core → Processor: drive pipeline · Analysis domain hands work to the job processor
- Processor → Extractor: crawl · Processor coordinates page discovery and extraction
- Processor → Checker: audit · Processor runs built-in and custom checks
- Processor → Reporting: summarize · Pipeline feeds results into report generation
- Extractor → SQLite Repos: persist pages · Extraction results are stored in SQLite
- Checker → SQLite Repos: persist issues · Audit findings are stored for later display
- Reporting → SQLite Repos: load patterns · Reporting reads templates, patterns, and analysis results
- AI → SQLite Repos: store insights · AI outputs and settings are persisted locally
- Local Model → SQLite Repos: store model state · Model metadata and configuration are persisted
- Licensing → SQLite Repos: store license · License records and entitlement state are persisted
- Tags & Ext → SQLite Repos: store customization · Tags and extension configuration are persisted
- SQLite Repos → Migrations: evolve schema · Schema changes define the SQLite data model
- SQLite Repos → SQLx Cache: verify queries · Offline SQLx metadata supports query checking
- Analysis Core → SQLite Repos: job data · Analysis domain reads and writes jobs, pages, links, and queues
- Processor → Lighthouse Runner: run performance · Processor invokes bundled native tooling for page analysis
