# thusitha2001/acl-blog-agent architecture

> Architecture diagram of the GitHub repository thusitha2001/acl-blog-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thusitha2001/acl-blog-agent
- Repository: https://github.com/thusitha2001/acl-blog-agent

## Overview

ACL Blog Agent is an SEO content workspace centered on turning a keyword or brief into a publish-ready article, with progress streamed to the browser. Its main workflow analyzes live search results, builds a brief, optionally scrapes a supplied site, retrieves grounding context, generates an article and scores it. Separate product branches support competitor audits, rewriting, and editing. The README documents these capabilities; the sampled excerpts do not expose every API route or internal call, so uncertain connections are omitted.

Main entry points: [`backend/acl_agent/pipeline_1click.py`](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/pipeline_1click.py) (One-click pipeline), [`frontend/app.js`](https://github.com/thusitha2001/acl-blog-agent/blob/main/frontend/app.js) (Browser workspace), [`backend/acl_agent/api.py`](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/api.py) (FastAPI API), [`backend/acl_agent/competitors.py`](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/competitors.py) (Competitor analysis)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_writing["Article generation"]
  node_pipeline["One-click pipeline<br/>[pipeline_1click.py]"]
  node_generation["Article generation<br/>[generation.py]"]
  node_validation["Quality validation<br/>[validation.py]"]
  node_scoring["SEO scoring<br/>[scoring.py]"]
  node_rewriter["Article rewriter<br/>[rewrite.py]"]
  node_article_result["Article and SEO output"]
end

subgraph group_research["Research and grounding"]
  node_serp_brief["SERP and brief<br/>[auto_brief.py]"]
  node_scraper["Website scraping<br/>[scraping.py]"]
  node_knowledge["Knowledge retrieval<br/>[knowledge_base.py]"]
end

subgraph group_workspace["Content workspace"]
  node_browser["Browser workspace<br/>[app.js]"]
  node_competitor_ui["Competitor workspace<br/>[competitors.js]"]
  node_editor["Article editor<br/>[editor.js]"]
end

subgraph group_analysis["SEO analysis"]
  node_competitor_analysis["Competitor analysis<br/>[competitors.py]"]
  node_gsc["Search Console diagnosis<br/>[gsc_diagnosis.py]"]
  node_analysis_advice["Analysis recommendations<br/>[analysis_llm.py]"]
end

subgraph group_services["Backend services"]
  node_api["FastAPI API<br/>[api.py]"]
  node_llm["Model client<br/>[llm.py]"]
  node_auth["Account service<br/>[auth.py]"]
  node_account_store[("Account records<br/>[auth.py]")]
end

node_writer_user(("Writer"))
node_search_engine["Search results"]
node_brand_site["User website"]
node_model_provider["LLM provider"]
node_search_console["Google Search Console"]

node_writer_user -->|"enters brief"| node_browser
node_browser -->|"POSTs generation"| node_api
node_api -->|"invokes"| node_pipeline
node_pipeline -->|"analyzes and briefs"| node_serp_brief
node_serp_brief -->|"queries results"| node_search_engine
node_pipeline -.->|"scrapes optionally"| node_scraper
node_scraper -.->|"fetches pages"| node_brand_site
node_pipeline -->|"retrieves context"| node_knowledge
node_pipeline -->|"generates draft"| node_generation
node_generation -->|"requests completion"| node_llm
node_llm -->|"calls model"| node_model_provider
node_pipeline -->|"scores article"| node_scoring
node_pipeline -->|"validates output"| node_validation
node_pipeline -->|"returns result"| node_api
node_api -->|"streams progress and result"| node_browser
node_browser -->|"renders"| node_article_result
node_writer_user -->|"submits audit"| node_competitor_ui
node_competitor_ui -->|"requests analysis"| node_api
node_api -->|"dispatches audit"| node_competitor_analysis
node_competitor_analysis -->|"checks SERP"| node_search_engine
node_competitor_analysis -->|"fetches pages"| node_brand_site
node_competitor_analysis -->|"uses diagnosis"| node_gsc
node_gsc -.->|"reads performance data"| node_search_console
node_competitor_analysis -->|"builds recommendations"| node_analysis_advice
node_analysis_advice -->|"requests advice"| node_llm
node_writer_user -->|"edits article"| node_editor
node_editor -->|"requests scoring"| node_api
node_writer_user -->|"requests rewrite"| node_browser
node_browser -->|"streams rewrite request"| node_rewriter
node_rewriter -->|"requests rewrite"| node_llm
node_browser -->|"submits credentials"| node_auth
node_auth -->|"reads and writes"| node_account_store
node_auth --> node_model_provider

click node_browser "https://github.com/thusitha2001/acl-blog-agent/blob/main/frontend/app.js"
click node_api "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/api.py"
click node_pipeline "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/pipeline_1click.py"
click node_serp_brief "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/auto_brief.py"
click node_scraper "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/scraping.py"
click node_knowledge "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/knowledge_base.py"
click node_generation "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/generation.py"
click node_llm "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/llm.py"
click node_validation "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/validation.py"
click node_scoring "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/scoring.py"
click node_competitor_ui "https://github.com/thusitha2001/acl-blog-agent/blob/main/frontend/competitors.js"
click node_competitor_analysis "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/competitors.py"
click node_gsc "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/gsc_diagnosis.py"
click node_analysis_advice "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/analysis_llm.py"
click node_rewriter "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/rewrite.py"
click node_editor "https://github.com/thusitha2001/acl-blog-agent/blob/main/frontend/editor.js"
click node_auth "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/auth.py"
click node_account_store "https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/auth.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_pipeline,node_generation,node_validation,node_scoring,node_rewriter,node_article_result,node_brand_site toneBlue
class node_serp_brief,node_scraper,node_knowledge toneAmber
class node_browser,node_competitor_ui,node_editor toneMint
class node_competitor_analysis,node_gsc,node_analysis_advice toneRose
class node_api,node_llm,node_auth,node_account_store,node_writer_user,node_search_engine,node_model_provider,node_search_console toneIndigo
```

## Components

### Article generation

- [One-click pipeline](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/pipeline_1click.py): `backend/acl_agent/pipeline_1click.py`
- [Article generation](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/generation.py): `backend/acl_agent/generation.py`
- [Quality validation](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/validation.py): `backend/acl_agent/validation.py`
- [SEO scoring](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/scoring.py): `backend/acl_agent/scoring.py`
- [Article rewriter](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/rewrite.py): `backend/acl_agent/rewrite.py`
- **Article and SEO output**

### Research and grounding

- [SERP and brief](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/auto_brief.py): `backend/acl_agent/auto_brief.py`
- [Website scraping](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/scraping.py): `backend/acl_agent/scraping.py`
- [Knowledge retrieval](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/knowledge_base.py): `backend/acl_agent/knowledge_base.py`

### Content workspace

- [Browser workspace](https://github.com/thusitha2001/acl-blog-agent/blob/main/frontend/app.js): `frontend/app.js`
- [Competitor workspace](https://github.com/thusitha2001/acl-blog-agent/blob/main/frontend/competitors.js): `frontend/competitors.js`
- [Article editor](https://github.com/thusitha2001/acl-blog-agent/blob/main/frontend/editor.js): `frontend/editor.js`

### SEO analysis

- [Competitor analysis](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/competitors.py): `backend/acl_agent/competitors.py`
- [Search Console diagnosis](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/gsc_diagnosis.py): `backend/acl_agent/gsc_diagnosis.py`
- [Analysis recommendations](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/analysis_llm.py): `backend/acl_agent/analysis_llm.py`

### Backend services

- [FastAPI API](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/api.py): `backend/acl_agent/api.py`
- [Model client](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/llm.py): `backend/acl_agent/llm.py`
- [Account service](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/auth.py): `backend/acl_agent/auth.py`
- [Account records](https://github.com/thusitha2001/acl-blog-agent/blob/main/backend/acl_agent/auth.py): `backend/acl_agent/auth.py`

### Other components

- **Writer**
- **Search results**
- **User website**
- **LLM provider**
- **Google Search Console**

## Connections

- Writer → Browser workspace: enters brief
- Browser workspace → FastAPI API: POSTs generation
- FastAPI API → One-click pipeline: invokes
- One-click pipeline → SERP and brief: analyzes and briefs
- SERP and brief → Search results: queries results
- One-click pipeline → Website scraping: scrapes optionally
- Website scraping → User website: fetches pages
- One-click pipeline → Knowledge retrieval: retrieves context
- One-click pipeline → Article generation: generates draft
- Article generation → Model client: requests completion
- Model client → LLM provider: calls model
- One-click pipeline → SEO scoring: scores article
- One-click pipeline → Quality validation: validates output
- One-click pipeline → FastAPI API: returns result
- FastAPI API → Browser workspace: streams progress and result
- Browser workspace → Article and SEO output: renders
- Writer → Competitor workspace: submits audit
- Competitor workspace → FastAPI API: requests analysis
- FastAPI API → Competitor analysis: dispatches audit
- Competitor analysis → Search results: checks SERP
- Competitor analysis → User website: fetches pages
- Competitor analysis → Search Console diagnosis: uses diagnosis
- Search Console diagnosis → Google Search Console: reads performance data
- Competitor analysis → Analysis recommendations: builds recommendations
- Analysis recommendations → Model client: requests advice
- Writer → Article editor: edits article
- Article editor → FastAPI API: requests scoring
- Writer → Browser workspace: requests rewrite
- Browser workspace → Article rewriter: streams rewrite request
- Article rewriter → Model client: requests rewrite
- Browser workspace → Account service: submits credentials
- Account service → Account records: reads and writes
- Account service → LLM provider