[Docs][Architecture] Add architecture documents

[davidzollo]

This PR reviews and refines the Chinese architecture documents in docs/zh/architecture for accuracy, removing obsolete implementation details and correcting configuration keys based on the current codebase.

[DanielCarter-stack]

Issue 1: English documentation missing maintenance note

Location: docs/en/architecture/*.md (all English architecture documentation)

Problem Description:
The Chinese documentation includes a note "说明：为降低维护成本并避免'文档代码/链接随重构漂移'，本文档不直接嵌入源码片段与源码链接", but the English documentation lacks a similar explanation.

Potential Risks:

• English documentation maintainers may not understand why source code links are not embedded
• Source code links may be added to English documentation in the future, increasing maintenance burden

Impact Scope:

• Direct Impact: English documentation maintainers
• Indirect Impact: Documentation and code synchronization maintenance costs
• Affected Area: All English architecture documentation

Severity: MINOR

Improvement Suggestion:
Add a note at the beginning of the English documentation:

> Note: To minimize maintenance overhead and avoid "documentation-code drift" due to refactoring, 
> this documentation focuses on component responsibilities, interaction flows, and design motivations 
> rather than embedding source code snippets or direct source links.

Rationale:

• Maintain consistency with Chinese documentation
• Help future maintainers understand the design decision
• Reduce confusion caused by inconsistent maintenance strategies between Chinese and English documentation

---

Issue 2: Missing documentation testing

Location: PR change root directory (recommend adding .github/workflows/docs-test.yml)

Problem Description:
This PR adds extensive documentation but does not include documentation testing CI, preventing automatic verification of:

• Markdown link validity (especially for relative paths like ../../seatunnel-api/...)
• Code example syntax correctness
• Synchronization between configuration keys and source code constants

Potential Risks:

• Documentation links become broken after code refactoring but cannot be detected in time
• Configuration keys change in code but documentation is not updated synchronously

Impact Scope:

• Direct Impact: Documentation reliability
• Indirect Impact: Users encounter errors when following documentation instructions
• Affected Area: All architecture documentation

Severity: MAJOR

Improvement Suggestion:
Add CI workflow example:

name: Docs Test

on:
  pull_request:
    paths:
      - 'docs/**'
      - 'seatunnel-api/**'
      - 'seatunnel-engine/**'

jobs:
  markdown-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check Markdown links
        uses: gaurav-nelson/github-action-markdown-link-check@v1
        with:
          config-file: '.markdownlinkcheck.json'
  
  config-keys-sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check config keys
        run: |
          # Example: Verify that configuration keys in the documentation exist in the code
          grep -r "multi_table_sink_replica" seatunnel-api || exit 1

Rationale:

• Automated documentation quality assurance
• Early detection of broken links and configuration key desynchronization
• Aligns with documentation testing best practices in modern projects

---

Issue 3: Storage implementation naming description in checkpoint-mechanism.md is not precise enough

Location: docs/en/architecture/fault-tolerance/checkpoint-mechanism.md:260

Related Context:

**Implementations**:
- `LocalFileCheckpointStorage`: Local file system (testing)
- `HdfsCheckpointStorage`: HDFS
- `S3CheckpointStorage`: AWS S3
- `OssCheckpointStorage`: Aliyun OSS

Problem Description:
Based on source code verification, the actual class names are:

• LocalFileStorage (not LocalFileCheckpointStorage)
• HdfsStorage (not HdfsCheckpointStorage)
• S3/OSS are not independent CheckpointStorage implementation classes, but are supported through HdfsStorage's S3Configuration/OssConfiguration

Potential Risks:

• Developers searching for the S3CheckpointStorage class according to the documentation will not find it
• Misleads users into thinking S3/OSS are independent plugins, when they actually share HdfsStorage

Impact Scope:

• Direct Impact: Developers looking for checkpoint storage implementations
• Indirect Impact: Users may find wrong documentation when configuring S3/OSS checkpoints
• Affected Area: checkpoint storage configuration

Severity: MAJOR

Improvement Suggestion:
Correct to:

**Implementations**:
- `LocalFileStorage`: Local file system (testing)
- `HdfsStorage`: Hadoop FileSystem-based backend; can work with HDFS/S3A/etc depending on Hadoop configuration

Note: S3 and OSS support are provided through Hadoop FileSystem configuration (e.g., `fs.s3a.impl`) rather than separate CheckpointStorage implementations.

Rationale:

• Consistent with actual code class names
• Accurately reflects the implementation approach of S3/OSS
• Avoids misleading developers into searching for non-existent classes

---

Issue 4: Resource management strategy class names are inaccurate

Location: docs/en/architecture/engine/resource-management.md

Related Context:
According to the review task document, strategy class names were corrected:

• Original documentation: RandomSlotAssignStrategy / SlotRatioSlotAssignStrategy / SystemLoadSlotAssignStrategy
• Actual code: RandomStrategy / SlotRatioStrategy / SystemLoadStrategy

Problem Description:
The English documentation (newly added) may still contain old class names (need to verify whether English documentation has applied the correction).

Potential Risks:

• Developers searching for RandomSlotAssignStrategy cannot find the actual class
• Misleads developers' understanding of strategy naming patterns

Impact Scope:

• Direct Impact: Developers looking for resource management strategy implementations
• Indirect Impact: Custom resource strategy development
• Affected Area: Resource management module

Severity: MAJOR

Improvement Suggestion:
Verify and correct strategy class names in English documentation (if not yet corrected):

**Slot Allocation Strategies**:
```java
// 1. RandomStrategy: Random selection among available workers
// 2. SlotRatioStrategy: Prefer workers with more available slots
// 3. SystemLoadStrategy: Prefer workers with lower CPU/memory usage

** Rationale**:
- 与实际代码类名一致
- 保持中英文文档对齐
- 确保开发者能找到正确的实现类

---

# ## Issue 5: Documentation Changes Not Updated in Developer Guide

** Location**: `docs/developer/` directory

** Problem Description**:
添加了大量架构文档，但开发者指南（如 `docs/developer/how-to-create-your-connector.md`）没有相应更新，添加指向新架构文档的链接。

** Potential Risks**:
- Connector 开发者可能不知道有架构文档可以参考
- 降低新架构文档的可见性和使用率

** Scope of Impact**:
- 直接影响: Connector 开发者
- 间接影响: 新架构文档的利用
- 影响面: Connector 开发流程

** Severity**: MINOR

** Recommendation**:
在 `docs/developer/how-to-create-your-connector.md` 中添加：
```markdown
## Architecture Reference

For detailed information on SeaTunnel's API design and engine architecture, see:

- [Architecture Overview](../architecture/overview.md)
- [Source Architecture](../architecture/api-design/source-architecture.md)
- [Sink Architecture](../architecture/api-design/sink-architecture.md)
- [Checkpoint Mechanism](../architecture/fault-tolerance/checkpoint-mechanism.md)

Rationale:

• Increase visibility of new architecture documentation
• Help Connector developers quickly find reference materials
• Improve overall usability of the documentation system

---

[misi1987107]

I think there are a bit too many subdirectories. Could we reduce them to optimize navigation efficiency.the directory structure I suggest is as follows，just for your consideration:
architecture
--overview.md
----design-philosophy.md
--api-design
----catalog-table.md
----sink-architecture.md
----source-architecture.md
----translation-layer.md
--engine
----engine-architecture.md
----dag-execution.md
----resource-management.md
--taskmechanism-design
----checkpoint-mechanism.md
----exactly-once.md
----multi-table.md

[misi1987107]

The structure of this module is incorrect

[misi1987107]

The structure of this module is incorrect

[misi1987107]

The resource has been removed

[misi1987107]

I don't know what the content under this title means, as there are no such two parts in other titles

[LiJie20190102]

LGTM

[davidzollo]

I think there are a bit too many subdirectories. Could we reduce them to optimize navigation efficiency.the directory structure I suggest is as follows，just for your consideration: architecture --overview.md ----design-philosophy.md --api-design ----catalog-table.md ----sink-architecture.md ----source-architecture.md ----translation-layer.md --engine ----engine-architecture.md ----dag-execution.md ----resource-management.md --taskmechanism-design ----checkpoint-mechanism.md ----exactly-once.md ----multi-table.md

Thanks for the suggestion! The directory structure feedback is valid — having translation-layer under a separate "Translation" category and multi-table under "Data Flow" was indeed inconsistent with where the files actually live. We've already addressed that in the latest commit by:

Moving translation-layer into the api-design/ category (matches its physical path)
Renaming "Data Flow" → "Features" and pointing it to architecture/features/multi-table
Regarding the broader restructure you proposed: the api-design/, engine/, and fault-tolerance/ groupings follow naming conventions already used in distributed systems projects (Flink, Spark, Kafka docs all use fault-tolerance as a top-level section). We'd prefer to keep that familiar terminology.

The main concern with taskmechanism-design is that multi-table is a data pipeline feature, not a task mechanism — grouping it alongside checkpoint-mechanism and exactly-once would be semantically misleading to readers looking for fault-tolerance topics.

A directory restructure would also require moving 24 files across both en/ and zh/, which is better scoped as a separate PR if there's consensus. Happy to continue the discussion there!

[zhangshenghang]

+1