# Project Architecture Showcase HTML Design

## Goal

Create a directly viewable static HTML page that introduces the current GEO Agent Article Optimizer project architecture, advantages, and customer-facing highlights.

The page is for customer demonstrations. It should first explain business value in plain language, then prove technical credibility through the actual architecture and workflow already present in the repository.

## Audience

Primary audience:

- Customer decision makers who need to understand value quickly.
- Customer-side technical evaluators who want to see whether the project is structured and extensible.

Tone:

- Mixed business and technical.
- Confident, concise, and presentation-ready.
- Chinese copy, because the current product UI and customer-facing workflow are Chinese-oriented.

## Output

Create one standalone HTML file:

```text
docs/project-architecture-showcase.html
```

The file must be usable by opening it directly in a browser. It must not require a Next.js dev server, external assets, CDN CSS, or network access.

## Content Structure

### 1. Hero

Present the project as:

```text
GEO 智能文章优化器
一个以事实卡为约束、以质量门禁为闭环的 AI 内容优化工作流
```

The hero should include compact capability labels:

- 事实卡约束
- 多节点 Agent 工作流
- QA 质量门禁
- 定向重写
- Markdown / Word / JSON 导出

### 2. Customer Problems And Solution

Explain the customer problems this project targets:

- 行业漂移。
- 公司名称不一致。
- 图片与正文不匹配。
- 第三方口吻出现在官方文章中。
- 平台语气和文章类型不匹配。
- 标题或正文语义不顺。
- 虚构资质、年限、案例或能力。
- 同一篇文章中产品、服务、年限前后冲突。

Then summarize the solution:

- First extract candidate facts.
- Ask the user to confirm or edit the fact card.
- Optimize only under confirmed facts.
- Run executable quality gates.
- Rewrite only failed sections.
- Export only after hard failures are cleared.

### 3. Architecture Overview

Show the actual workflow as a visual HTML/CSS flow:

```text
Article Input
→ InputNormalizer
→ FactExtractor
→ UserConfirmedFactCard
→ ArticleOptimizer
→ QualityInspector
→ TargetedRewriter
→ Exporter
```

The page should make clear that `TargetedRewriter` loops back into `QualityInspector` for up to two rewrite rounds.

### 4. Layered Code Architecture

Introduce the repository layers:

- `src/app`: Next.js page and API route handlers.
- `src/components`: focused UI panels for input, fact card, preview, and QA report.
- `src/lib/domain`: shared TypeScript types and Zod validation schemas.
- `src/lib/workflow`: independent workflow nodes for normalization, extraction, optimization, QA, rewriting, exporting, and orchestration.
- `src/lib/llm`: provider abstraction for DeepSeek and OpenAI-compatible models.
- `src/lib/db`: local SQLite connection, schema, and repositories.
- `tests` and `src/**/__tests__`: Vitest and Playwright coverage for domain, database, workflow, API, and MVP behavior.

### 5. Technical Highlights

Highlight advantages grounded in the current codebase:

- Confirmed facts are hard constraints, reducing hallucination risk.
- Workflow nodes are separated, making individual steps testable and replaceable.
- Quality checks are structured as `pass`, `warn`, or `fail`.
- Hard QA failures block export.
- Failed checks trigger targeted rewriting instead of full-document blind regeneration.
- LLM calls are isolated in a provider client, so model vendors can be swapped later.
- Missing credentials fall back to deterministic local behavior for tests and local review.
- Local SQLite storage makes the MVP simple to deploy and suitable for internal demonstration.
- Markdown, Word, and JSON exports support both human review and system integration.

### 6. MVP Boundary And Expansion

State current MVP boundaries honestly:

- Pasted text only.
- Local SQLite only.
- No account permissions.
- No collaboration.
- No publishing platform APIs.
- No batch queue.
- Basic Word export layout.

Then list natural expansion paths:

- `.docx` parsing and template export.
- Multi-brand fact-card library.
- Batch optimization queue.
- Team review and approval workflow.
- Publishing platform integration.
- More quality gates and industry-specific rule packs.

## Visual Direction

Style the page as a polished customer demo page:

- Dark professional background.
- Clear white and light gray text.
- One or two restrained accent colors.
- No external fonts or images.
- Use CSS cards only for repeated information units.
- Use responsive layout that works on desktop and mobile.
- Avoid marketing filler. Every section should communicate project value or architecture.

## Acceptance Criteria

- `docs/project-architecture-showcase.html` exists.
- The file opens directly in a browser without a build step.
- The page is written in Chinese.
- The architecture and highlights match the existing project structure.
- The page includes business value, workflow architecture, code-layer architecture, technical advantages, MVP limits, and expansion paths.
- The page has responsive CSS in the same file.
- No external network resources are required.

