# Blog Post Documentation Framework Visualization

**Last Updated:** 2026-01-28

This document provides a visual representation of the blog post documentation framework used in this project.

## Framework Overview

```mermaid
graph TB
    subgraph "Blog Post Source"
        WP[WordPress Blog Post]
        JSON[v2/data/blog/posts/<br/>post-slug.json]
    end

    subgraph "Analysis Scripts"
        AC[analyze-post-content.php]
        AS[analyze-post-seo.php]
        AL[analyze-post-links.php]
        CS[collect-post-keywords-sistrix.php]
        CG[collect-post-performance-ga4.php]
        CC[collect-post-performance-gsc.php]
        MR[map-post-related-resources.php]
    end

    subgraph "Data Files<br/>docs/content/blog/posts/{category}/{slug}/data/"
        CA[content-analysis.json]
        SA[seo-analysis.json]
        LA[links-analysis.json]
        KS[keywords-sistrix.json]
        GA[performance-ga4.json]
        GS[performance-gsc.json]
        RR[related-resources.json]
        SI[search-intent.json]
        SF[serp-features.json]
        CL[competition-levels.json]
        DO[domain-opportunities.json]
    end

    subgraph "Automated Reports<br/>data/reports/"
        CAR[content-analysis-report.md]
        SPR[seo-performance-report.md]
        KOR[keyword-opportunities-report.md]
        TAR[traffic-analysis-report.md]
        PSR[prioritization-score-report.md]
    end

    subgraph "Master Documentation<br/>docs/content/blog/posts/{category}/{slug}/"
        PA[POST_ANALSIS.md<br/>Content Analysis]
        SR[SEO_REPORT.md<br/>SEO Performance]
        IL[INTERNAL_LINKS.md<br/>Link Analysis]
        IP[IMPROVEMENT_PLAN.md<br/>Action Plan]
        MN[MANUAL_NOTES.md<br/>Manual Review]
    end

    subgraph "Documentation Generator"
        GD[generate-post-documentation.php]
        GR[generate-automated-reports.php]
    end

    subgraph "Workflow"
        W1[1. Data Collection]
        W2[2. Analysis Generation]
        W3[3. Report Generation]
        W4[4. Documentation Generation]
        W5[5. Manual Review]
    end

    %% Data Flow
    WP --> JSON
    JSON --> AC
    JSON --> AS
    JSON --> AL

    AC --> CA
    AS --> SA
    AL --> LA
    CS --> KS
    CG --> GA
    CC --> GS
    MR --> RR

    CA --> GD
    SA --> GD
    LA --> GD
    KS --> GD
    GA --> GD
    GS --> GD
    RR --> GD
    SI --> GD
    SF --> GD
    CL --> GD
    DO --> GD

    GD --> GR
    GR --> CAR
    GR --> SPR
    GR --> KOR
    GR --> TAR
    GR --> PSR

    GD --> PA
    GD --> SR
    GD --> IL
    GD --> IP

    CAR --> PA
    SPR --> SR
    KOR --> SR
    TAR --> PA
    PSR --> IP

    PA --> W5
    SR --> W5
    IL --> W5
    IP --> W5
    W5 --> MN

    %% Styling
    classDef script fill:#e1f5ff,stroke:#01579b,stroke-width:2px
    classDef data fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef report fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef doc fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef workflow fill:#fff9c4,stroke:#f57f17,stroke-width:2px

    class AC,AS,AL,CS,CG,CC,MR,GD,GR script
    class CA,SA,LA,KS,GA,GS,RR,SI,SF,CL,DO data
    class CAR,SPR,KOR,TAR,PSR report
    class PA,SR,IL,IP,MN doc
    class W1,W2,W3,W4,W5 workflow
```

## Detailed Structure Diagram

```mermaid
graph LR
    subgraph "Blog Post Documentation Structure"
        subgraph "Category Level"
            CAT[Category:<br/>lexikon / ratgeber / inside-ordio]
        end

        subgraph "Post Level: docs/content/blog/posts/{category}/{slug}/"
            PA2[POST_ANALYSIS.md<br/>━━━━━━━━━━━━━━━━━━━━<br/>• Post metadata<br/>• Content quality<br/>• Topic coverage<br/>• Content gaps<br/>• FAQ analysis]

            SR2[SEO_REPORT.md<br/>━━━━━━━━━━━━━━━━━━━━<br/>• Target keywords<br/>• LSI keywords<br/>• Performance metrics<br/>• Meta tags review<br/>• SEO score]

            IL2[INTERNAL_LINKS.md<br/>━━━━━━━━━━━━━━━━━━━━<br/>• Current links inventory<br/>• Related posts carousel<br/>• Missing link opportunities<br/>• Link quality assessment]

            IP2[IMPROVEMENT_PLAN.md<br/>━━━━━━━━━━━━━━━━━━━━<br/>• Content improvements<br/>• SEO optimizations<br/>• Internal linking<br/>• Supporting elements<br/>• Priority ranking<br/><br/>⚠️ Ratgeber/Lexikon only]

            MN2[MANUAL_NOTES.md<br/>━━━━━━━━━━━━━━━━━━━━<br/>• Manual review notes<br/>• Expert insights<br/>• Human observations<br/>• Never overwritten]
        end

        subgraph "Data Directory: data/"
            subgraph "Analysis Data"
                CA2[content-analysis.json]
                SA2[seo-analysis.json]
                LA2[links-analysis.json]
            end

            subgraph "Performance Data"
                KS2[keywords-sistrix.json]
                GA2[performance-ga4.json]
                GS2[performance-gsc.json]
            end

            subgraph "Related Data"
                RR2[related-resources.json]
                SI2[search-intent.json]
                SF2[serp-features.json]
            end

            subgraph "Competitive Data"
                CL2[competition-levels.json]
                DO2[domain-opportunities.json]
            end

            subgraph "Reports: data/reports/"
                CAR2[content-analysis-report.md]
                SPR2[seo-performance-report.md]
                KOR2[keyword-opportunities-report.md]
                TAR2[traffic-analysis-report.md]
                PSR2[prioritization-score-report.md]
            end
        end
    end

    CAT --> PA2
    CAT --> SR2
    CAT --> IL2
    CAT --> IP2
    CAT --> MN2

    CA2 --> PA2
    SA2 --> SR2
    LA2 --> IL2
    CA2 --> IP2
    SA2 --> IP2
    LA2 --> IP2

    KS2 --> SR2
    GA2 --> SR2
    GS2 --> SR2
    GA2 --> PA2
    GS2 --> PA2

    CAR2 --> PA2
    SPR2 --> SR2
    KOR2 --> SR2
    TAR2 --> PA2
    PSR2 --> IP2

    %% Styling
    classDef category fill:#bbdefb,stroke:#0277bd,stroke-width:3px
    classDef doc fill:#c8e6c9,stroke:#2e7d32,stroke-width:2px
    classDef data fill:#fff9c4,stroke:#f9a825,stroke-width:2px
    classDef report fill:#f8bbd0,stroke:#c2185b,stroke-width:2px

    class CAT category
    class PA2,SR2,IL2,IP2,MN2 doc
    class CA2,SA2,LA2,KS2,GA2,GS2,RR2,SI2,SF2,CL2,DO2 data
    class CAR2,SPR2,KOR2,TAR2,PSR2 report
```

## Workflow Diagram

```mermaid
flowchart TD
    START([Start: New Blog Post]) --> COLLECT[Data Collection Phase]

    COLLECT --> C1[collect-post-keywords-sistrix.php<br/>SISTRIX API]
    COLLECT --> C2[collect-post-performance-ga4.php<br/>Google Analytics 4]
    COLLECT --> C3[collect-post-performance-gsc.php<br/>Google Search Console]
    COLLECT --> C4[map-post-related-resources.php<br/>Related Tools/Templates]

    C1 --> DATA1[keywords-sistrix.json]
    C2 --> DATA2[performance-ga4.json]
    C3 --> DATA3[performance-gsc.json]
    C4 --> DATA4[related-resources.json]

    DATA1 --> ANALYZE[Analysis Phase]
    DATA2 --> ANALYZE
    DATA3 --> ANALYZE
    DATA4 --> ANALYZE

    ANALYZE --> A1[analyze-post-content.php]
    ANALYZE --> A2[analyze-post-seo.php]
    ANALYZE --> A3[analyze-post-links.php]

    A1 --> DATA5[content-analysis.json]
    A2 --> DATA6[seo-analysis.json]
    A3 --> DATA7[links-analysis.json]

    DATA5 --> REPORTS[Report Generation Phase]
    DATA6 --> REPORTS
    DATA7 --> REPORTS
    DATA1 --> REPORTS
    DATA2 --> REPORTS
    DATA3 --> REPORTS

    REPORTS --> R1[generate-automated-reports.php]
    R1 --> REP1[content-analysis-report.md]
    R1 --> REP2[seo-performance-report.md]
    R1 --> REP3[keyword-opportunities-report.md]
    R1 --> REP4[traffic-analysis-report.md]
    R1 --> REP5[prioritization-score-report.md]

    REP1 --> DOCS[Documentation Generation Phase]
    REP2 --> DOCS
    REP3 --> DOCS
    REP4 --> DOCS
    REP5 --> DOCS

    DOCS --> D1[generate-post-documentation.php]

    D1 --> DOC1[POST_ANALYSIS.md]
    D1 --> DOC2[SEO_REPORT.md]
    D1 --> DOC3[INTERNAL_LINKS.md]
    D1 --> DOC4{Category?}

    DOC4 -->|Ratgeber/Lexikon| DOC5[IMPROVEMENT_PLAN.md]
    DOC4 -->|inside-ordio| SKIP[Skip IMPROVEMENT_PLAN]

    DOC1 --> MANUAL[Manual Review Phase]
    DOC2 --> MANUAL
    DOC3 --> MANUAL
    DOC5 --> MANUAL

    MANUAL --> M1[Review POST_ANALYSIS.md]
    MANUAL --> M2[Review SEO_REPORT.md]
    MANUAL --> M3[Review INTERNAL_LINKS.md]
    MANUAL --> M4[Review IMPROVEMENT_PLAN.md]

    M1 --> NOTES[Add Manual Notes]
    M2 --> NOTES
    M3 --> NOTES
    M4 --> NOTES

    NOTES --> MANUALNOTES[MANUAL_NOTES.md<br/>Never overwritten]

    MANUALNOTES --> REGEN{Need to Regenerate?}

    REGEN -->|Yes| SAFE[safe-regenerate-documentation.php<br/>Preserves manual sections]
    REGEN -->|No| COMPLETE([Documentation Complete])

    SAFE --> DOCS

    %% Styling
    classDef phase fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
    classDef script fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef data fill:#f1f8e9,stroke:#558b2f,stroke-width:2px
    classDef doc fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    classDef decision fill:#fff9c4,stroke:#f57f17,stroke-width:2px

    class COLLECT,ANALYZE,REPORTS,DOCS,MANUAL phase
    class C1,C2,C3,C4,A1,A2,A3,R1,D1,SAFE script
    class DATA1,DATA2,DATA3,DATA4,DATA5,DATA6,DATA7 data
    class DOC1,DOC2,DOC3,DOC5,REP1,REP2,REP3,REP4,REP5,MANUALNOTES doc
    class DOC4,REGEN decision
```

## File Relationships

```mermaid
graph TB
    subgraph "Source Data"
        JSON[v2/data/blog/posts/<br/>post-slug.json<br/>━━━━━━━━━━━━━━━━━━━━<br/>• Post content<br/>• Metadata<br/>• WordPress data]
    end

    subgraph "Generated Data Files"
        CA[content-analysis.json]
        SA[seo-analysis.json]
        LA[links-analysis.json]
        KS[keywords-sistrix.json]
        GA[performance-ga4.json]
        GS[performance-gsc.json]
        RR[related-resources.json]
    end

    subgraph "Master Documentation"
        PA[POST_ANALYSIS.md]
        SR[SEO_REPORT.md]
        IL[INTERNAL_LINKS.md]
        IP[IMPROVEMENT_PLAN.md]
    end

    subgraph "Automated Reports"
        CAR[content-analysis-report.md]
        SPR[seo-performance-report.md]
        KOR[keyword-opportunities-report.md]
        TAR[traffic-analysis-report.md]
        PSR[prioritization-score-report.md]
    end

    JSON --> CA
    JSON --> SA
    JSON --> LA

    CA --> CAR
    SA --> SPR
    SA --> KOR
    GA --> TAR
    GS --> TAR
    CA --> PSR
    SA --> PSR

    CAR --> PA
    SPR --> SR
    KOR --> SR
    TAR --> PA
    PSR --> IP

    CA --> PA
    SA --> SR
    LA --> IL
    KS --> SR
    GA --> SR
    GS --> SR
    RR --> IL
    CA --> IP
    SA --> IP
    LA --> IP

    %% Manual sections preserved
    PA -.->|Manual Sections<br/>Preserved| PA
    SR -.->|Manual Sections<br/>Preserved| SR
    IL -.->|Manual Sections<br/>Preserved| IL
    IP -.->|Manual Sections<br/>Preserved| IP

    %% Styling
    classDef source fill:#e1f5ff,stroke:#01579b,stroke-width:3px
    classDef data fill:#fff3e0,stroke:#e65100,stroke-width:2px
    classDef doc fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px
    classDef report fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef manual stroke:#d32f2f,stroke-width:2px,stroke-dasharray: 5 5

    class JSON source
    class CA,SA,LA,KS,GA,GS,RR data
    class PA,SR,IL,IP doc
    class CAR,SPR,KOR,TAR,PSR report
```

## Key Features

### 1. **Dual-Structure Documentation**

- **Automated Reports** (`data/reports/`): Detailed automated analysis, can be regenerated
- **Master Documentation** (root): Quick summaries + editable manual sections

### 2. **Manual Section Preservation**

- Content between `<!-- BEGIN MANUAL -->` and `<!-- END MANUAL -->` markers is preserved during regeneration
- Manual edits are never overwritten by scripts

### 3. **Category-Specific Documentation**

- **Ratgeber & Lexikon**: Include `IMPROVEMENT_PLAN.md`
- **inside-ordio**: Documentation only, no improvement plans

### 4. **Data-Driven Analysis**

- SISTRIX keyword data
- Google Analytics 4 metrics
- Google Search Console data
- Related resources mapping
- Search intent analysis
- SERP features analysis

### 5. **Comprehensive Coverage**

Each blog post documentation includes:

- Content quality assessment
- SEO performance tracking
- Internal linking analysis
- Improvement recommendations
- Manual review notes

## Usage

### For Team Members

1. Navigate to `docs/content/blog/posts/{category}/{slug}/`
2. Review `POST_ANALYSIS.md` for content insights
3. Check `SEO_REPORT.md` for performance metrics
4. Review `INTERNAL_LINKS.md` for linking opportunities
5. Follow `IMPROVEMENT_PLAN.md` for actionable improvements
6. Add notes to manual sections as needed

### For AI Agents

1. Check `.cursor/rules/blog-post-documentation.mdc` for rules
2. Use `generate-post-documentation.php` to create/update docs
3. Use `safe-regenerate-documentation.php` to update while preserving manual edits
4. Reference data files in `data/` directory for analysis

## Related Documentation

- [Blog Post Documentation Structure](posts/README.md)
- [Manual Review Workflow](guides/MANUAL_REVIEW_WORKFLOW.md)
- [Data Collection Guide](guides/DATA_COLLECTION_GUIDE.md)
- [Improvement Process Guide](BLOG_POST_IMPROVEMENT_PROCESS.md)