# anasmohtaj-cell/seo_agent architecture

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

- Interactive diagram: https://gitdiagram.com/anasmohtaj-cell/seo_agent
- Repository: https://github.com/anasmohtaj-cell/seo_agent

## Overview

This repository is a small SEO operations service: HTTP requests launch site crawls and technical audits, expose their findings and reports, and apply or roll back publishing changes. The crawl and audit paths use in-memory state; audits analyze crawled pages with Lighthouse, while publishing delegates changes through a CMS connector. The README provides no architectural detail, so the graph follows the shown routes and source references; WordPress is imported by the publishing controller but its use is not shown.

Main entry points: [`src/agents/technical/technicalAgent.ts`](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/technical/technicalAgent.ts) (Technical Agent), [`src/server.ts`](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/server.ts) (Express Server), [`src/agents/publishing/PublishingAgent.ts`](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/publishing/PublishingAgent.ts) (Publishing Agent), [`src/controllers/technicalController.ts`](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/controllers/technicalController.ts) (Audit Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["Express Server<br/>[server.ts]"]
  node_crawl_routes["Crawl Routes<br/>[crawlRoutes.ts]"]
  node_crawl_controller["Crawl Controller<br/>[crawlController.ts]"]
  node_technical_routes["Audit Routes<br/>[technicalRoutes.ts]"]
  node_technical_controller["Audit Controller"]
  node_publishing_routes["Publishing Routes"]
  node_publishing_controller["Publishing Controller"]
end

subgraph group_crawl["Crawl"]
  node_crawler["Crawl Agent<br/>[CrawlAgent.ts]"]
  node_finding_types["Finding Types<br/>[finding.ts]"]
end

subgraph group_audit["Technical Audit"]
  node_technical_agent["Technical Agent<br/>[technicalAgent.ts]"]
  node_lighthouse["Lighthouse"]
  node_technical_types["Report Types<br/>[technicalReport.ts]"]
end

subgraph group_publishing["Publishing"]
  node_publishing_agent["Publishing Agent<br/>[PublishingAgent.ts]"]
  node_publishing_types["Publishing Types<br/>[publishing.ts]"]
end

subgraph group_state["State and Connectors"]
  node_crawl_store[("Crawl Agent Store<br/>[crawlAgentStore.ts]")]
  node_report_store[("Report Store")]
  node_publishing_store[("Publishing Store<br/>[publishingStore.ts]")]
  node_cms_interface["CMS Connector<br/>[CMSConnector.ts]"]
  node_mock_cms["Mock CMS"]
  node_wordpress["WordPress Connector"]
  node_site_service["Site Service<br/>[siteServices.ts]"]
end

node_user(("API Client"))

node_user -->|"sends requests"| node_server
node_server -->|"mounts routes"| node_crawl_routes
node_server -->|"mounts routes"| node_technical_routes
node_server -->|"mounts routes"| node_publishing_routes
node_crawl_routes -->|"routes requests"| node_crawl_controller
node_technical_routes -->|"routes requests"| node_technical_controller
node_publishing_routes -->|"routes requests"| node_publishing_controller
node_crawl_controller -->|"starts crawl; reads findings"| node_crawl_store
node_crawl_store -->|"holds agent"| node_crawler
node_crawler -->|"uses types"| node_finding_types
node_technical_controller -->|"starts audit"| node_technical_agent
node_technical_controller -->|"reads report"| node_report_store
node_technical_agent -->|"gets pages"| node_crawl_store
node_technical_agent -->|"audits pages"| node_lighthouse
node_technical_agent -->|"saves report"| node_report_store
node_technical_agent -->|"builds reports"| node_technical_types
node_technical_agent -->|"constructs service"| node_site_service
node_publishing_controller -->|"applies or rolls back"| node_publishing_agent
node_publishing_controller -->|"configures connector"| node_mock_cms
node_publishing_agent -->|"uses history store"| node_publishing_store
node_publishing_agent -->|"applies changes through"| node_cms_interface
node_publishing_agent -->|"uses types"| node_publishing_types
node_mock_cms -.->|"implements contract"| node_cms_interface
node_wordpress -.->|"implements contract"| node_cms_interface

click node_server "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/server.ts"
click node_crawl_routes "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/routes/crawlRoutes.ts"
click node_crawl_controller "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/controllers/crawlController.ts"
click node_technical_routes "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/routes/technicalRoutes.ts"
click node_technical_controller "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/controllers/technicalController.ts"
click node_publishing_routes "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/routes/publishingRoutes.ts"
click node_publishing_controller "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/controllers/publishingController.ts"
click node_crawler "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/crawl/CrawlAgent.ts"
click node_finding_types "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/types/finding.ts"
click node_technical_agent "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/technical/technicalAgent.ts"
click node_technical_types "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/types/technicalReport.ts"
click node_publishing_agent "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/publishing/PublishingAgent.ts"
click node_publishing_types "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/types/publishing.ts"
click node_crawl_store "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/crawlAgentStore.ts"
click node_report_store "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/technicalReportStore.ts"
click node_publishing_store "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/publishingStore.ts"
click node_cms_interface "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/connectors/CMSConnector.ts"
click node_mock_cms "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/connectors/MockCMSConnector.ts"
click node_wordpress "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/connectors/wordpress/WordPressConnector.ts"
click node_site_service "https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/siteServices.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_server,node_crawl_routes,node_crawl_controller,node_technical_routes,node_technical_controller,node_publishing_routes,node_publishing_controller,node_user toneBlue
class node_crawler,node_finding_types toneAmber
class node_technical_agent,node_lighthouse,node_technical_types toneMint
class node_publishing_agent,node_publishing_types toneRose
class node_crawl_store,node_report_store,node_publishing_store,node_cms_interface,node_mock_cms,node_wordpress,node_site_service toneIndigo
```

## Components

### HTTP API

- [Express Server](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/server.ts): `src/server.ts`
- [Crawl Routes](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/routes/crawlRoutes.ts): `src/routes/crawlRoutes.ts`
- [Crawl Controller](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/controllers/crawlController.ts): `src/controllers/crawlController.ts`
- [Audit Routes](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/routes/technicalRoutes.ts): `src/routes/technicalRoutes.ts`
- [Audit Controller](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/controllers/technicalController.ts): `src/controllers/technicalController.ts`
- [Publishing Routes](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/routes/publishingRoutes.ts): `src/routes/publishingRoutes.ts`
- [Publishing Controller](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/controllers/publishingController.ts): `src/controllers/publishingController.ts`

### Crawl

- [Crawl Agent](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/crawl/CrawlAgent.ts): `src/agents/crawl/CrawlAgent.ts`
- [Finding Types](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/types/finding.ts): `src/types/finding.ts`

### Technical Audit

- [Technical Agent](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/technical/technicalAgent.ts): `src/agents/technical/technicalAgent.ts`
- **Lighthouse**
- [Report Types](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/types/technicalReport.ts): `src/types/technicalReport.ts`

### Publishing

- [Publishing Agent](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/agents/publishing/PublishingAgent.ts): `src/agents/publishing/PublishingAgent.ts`
- [Publishing Types](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/types/publishing.ts): `src/types/publishing.ts`

### State and Connectors

- [Crawl Agent Store](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/crawlAgentStore.ts): `src/services/crawlAgentStore.ts`
- [Report Store](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/technicalReportStore.ts): `src/services/technicalReportStore.ts`
- [Publishing Store](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/publishingStore.ts): `src/services/publishingStore.ts`
- [CMS Connector](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/connectors/CMSConnector.ts): `src/connectors/CMSConnector.ts`
- [Mock CMS](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/connectors/MockCMSConnector.ts): `src/connectors/MockCMSConnector.ts`
- [WordPress Connector](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/connectors/wordpress/WordPressConnector.ts): `src/connectors/wordpress/WordPressConnector.ts`
- [Site Service](https://github.com/anasmohtaj-cell/seo_agent/blob/main/src/services/siteServices.ts): `src/services/siteServices.ts`

### Other components

- **API Client**

## Connections

- API Client → Express Server: sends requests
- Express Server → Crawl Routes: mounts routes (evidence: `src/server.ts`)
- Express Server → Audit Routes: mounts routes (evidence: `src/server.ts`)
- Express Server → Publishing Routes: mounts routes (evidence: `src/server.ts`)
- Crawl Routes → Crawl Controller: routes requests (evidence: `src/routes/crawlRoutes.ts`)
- Audit Routes → Audit Controller: routes requests (evidence: `src/routes/technicalRoutes.ts`)
- Publishing Routes → Publishing Controller: routes requests (evidence: `src/routes/publishingRoutes.ts`)
- Crawl Controller → Crawl Agent Store: starts crawl; reads findings (evidence: `src/controllers/crawlController.ts`)
- Crawl Agent Store → Crawl Agent: holds agent (evidence: `src/services/crawlAgentStore.ts`)
- Crawl Agent → Finding Types: uses types (evidence: `src/agents/crawl/CrawlAgent.ts`)
- Audit Controller → Technical Agent: starts audit (evidence: `src/controllers/technicalController.ts`)
- Audit Controller → Report Store: reads report (evidence: `src/controllers/technicalController.ts`)
- Technical Agent → Crawl Agent Store: gets pages (evidence: `src/agents/technical/technicalAgent.ts`)
- Technical Agent → Lighthouse: audits pages (evidence: `src/agents/technical/technicalAgent.ts`)
- Technical Agent → Report Store: saves report (evidence: `src/agents/technical/technicalAgent.ts`)
- Technical Agent → Report Types: builds reports (evidence: `src/agents/technical/technicalAgent.ts`)
- Technical Agent → Site Service: constructs service (evidence: `src/agents/technical/technicalAgent.ts`)
- Publishing Controller → Publishing Agent: applies or rolls back (evidence: `src/controllers/publishingController.ts`)
- Publishing Controller → Mock CMS: configures connector (evidence: `src/controllers/publishingController.ts`)
- Publishing Agent → Publishing Store: uses history store (evidence: `src/agents/publishing/PublishingAgent.ts`)
- Publishing Agent → CMS Connector: applies changes through (evidence: `src/agents/publishing/PublishingAgent.ts`)
- Publishing Agent → Publishing Types: uses types (evidence: `src/agents/publishing/PublishingAgent.ts`)
- Mock CMS → CMS Connector: implements contract (evidence: `src/connectors/MockCMSConnector.ts`)
- WordPress Connector → CMS Connector: implements contract (evidence: `src/connectors/wordpress/WordPressConnector.ts`)
