🔄 EU Parliament Monitor — Flowcharts

Process & Data Flow Documentation for European Parliament Intelligence
📈 Security Flows • 🔄 CI/CD Pipeline • 📊 Data Processing

📋 Document Owner: CEO | 📄 Version: 1.2 | 📅 Last Updated: 2026-04-20 (UTC) | 🏷️ Platform Release: v0.8.40
🔄 Review Cycle: Quarterly | ⏰ Next Review: 2026-07-20

📚 Architecture Documentation Map

Document	Focus	Description	Documentation Link
Architecture	🏛️ Architecture	C4 model showing current system structure	View Source
Future Architecture	🏛️ Architecture	C4 model showing future system structure	View Source
Mindmaps	🧠 Concept	Current system component relationships	View Source
Future Mindmaps	🧠 Concept	Future capability evolution	View Source
SWOT Analysis	💼 Business	Current strategic assessment	View Source
Future SWOT Analysis	💼 Business	Future strategic opportunities	View Source
Data Model	📊 Data	Current data structures and relationships	View Source
Future Data Model	📊 Data	Enhanced European Parliament data architecture	View Source
Flowcharts	🔄 Process	Current data processing workflows	View Source
Future Flowcharts	🔄 Process	Enhanced AI-driven workflows	View Source
State Diagrams	🔄 Behavior	Current system state transitions	View Source
Future State Diagrams	🔄 Behavior	Enhanced adaptive state transitions	View Source
Security Architecture	🛡️ Security	Current security implementation	View Source
Future Security Architecture	🛡️ Security	Security enhancement roadmap	View Source
Threat Model	🎯 Security	STRIDE threat analysis	View Source
Classification	🏷️ Governance	CIA classification & BCP	View Source
CRA Assessment	🛡️ Compliance	Cyber Resilience Act	View Source
Workflows	⚙️ DevOps	CI/CD documentation	View Source
Future Workflows	🚀 DevOps	Planned CI/CD enhancements	View Source
Business Continuity Plan	🔄 Resilience	Recovery planning	View Source
Financial Security Plan	💰 Financial	Cost & security analysis	View Source
End-of-Life Strategy	📦 Lifecycle	Technology EOL planning	View Source
Unit Test Plan	🧪 Testing	Unit testing strategy	View Source
E2E Test Plan	🔍 Testing	End-to-end testing	View Source
Performance Testing	⚡ Performance	Performance benchmarks	View Source
Security Policy	🔒 Security	Vulnerability reporting & security policy	View Source

📋 Overview

This document provides detailed process flow diagrams showing security controls, data flows, and decision points in the EU Parliament Monitor platform.

🛡️ ISMS Policy Alignment

This document aligns with Hack23's Information Security Management System (ISMS) policies and ISO 27001:2022 controls. All flowcharts demonstrate implementation of security controls required by these policies.

Policy Mapping

ISMS Policy	ISO 27001 Control	Document Section	Description
Information Security Policy	A.5.1	All sections	Overarching security governance framework
Secure Development Policy	A.8.25, A.8.28	News Generation Security Flow, CI/CD Security Pipeline	Secure coding practices, input validation, code review
Access Control Policy	A.5.15, A.5.18	MCP Client Connection Security Flow	Authentication, authorization, least privilege
Vulnerability Management Policy	A.8.8	Vulnerability Management Workflow	Vulnerability scanning, remediation, patch management
Incident Response Policy	A.5.24, A.5.25, A.5.26	Incident Response Flow	Detection, response, recovery, post-incident review
Change Management Policy	A.8.32	CI/CD Security Pipeline, Release Workflow	Controlled deployments, testing, approval gates
Cryptography Policy	A.8.24	Content Delivery Security Flow, Deployment Security Flow	TLS 1.3, HTTPS-only, cryptographic signatures

Key Security Principles Demonstrated

Defense in Depth: Multiple security layers (validation, sanitization, encoding, CSP)
Least Privilege: Minimal permissions for GitHub Actions, MCP connections
Secure by Default: HTTPS-only, CSP enforcement, input validation at every stage
Fail Secure: Fallback content on validation failures, graceful degradation
Separation of Duties: Automated checks, required approvals, independent verification
Continuous Monitoring: Dependabot, CodeQL, npm audit, health checks
Incident Response: Defined severity levels, escalation paths, post-mortem reviews
Supply Chain Security: SBOM generation, SLSA attestations, dependency scanning

Compliance Framework Coverage

ISO 27001:2022: Controls A.5.1, A.5.15, A.5.18, A.5.24, A.5.25, A.5.26, A.8.8, A.8.24, A.8.25, A.8.28, A.8.32
NIST CSF 2.0: Identify (ID.RA, ID.SC), Protect (PR.AC, PR.DS, PR.IP), Detect (DE.CM), Respond (RS.AN, RS.MI), Recover (RC.RP)
CIS Controls v8.1: Controls 1, 4, 6, 8, 10, 16, 18
GDPR: Article 25 (Data protection by design), Article 32 (Security of processing)
NIS2 Directive: Risk management, incident handling, supply chain security
EU Cyber Resilience Act: Secure by default, vulnerability disclosure, security updates

🔐 News Generation Security Flow

The end-to-end agentic news generation flow spans gh-aw runtime, Stage A→E protocol, AI-First 2-pass analysis, Stage-C completeness gate, and safe-output PR creation. The 9 news workflows — 8 article-generating (news-breaking, news-week-in-review, news-month-in-review, news-week-ahead, news-month-ahead, news-committee-reports, news-motions, news-propositions) + the manual news-translate helper — all share this spine.

flowchart TD
    Start["🚀 Schedule / workflow_dispatch\nnews-{breaking,weekly,monthly,\nweek-ahead,month-ahead,\ncommittee-reports,motions,propositions}"] --> Sandbox["🛡️ Sandboxed Docker runner\nubuntu-latest 2-core\n120-min hard timeout\n(executes pre-compiled .lock.yml)"]

    Sandbox --> MCPSetup["📡 scripts/mcp-setup.sh\nEP_MCP_GATEWAY_URL=\nhttp://host.docker.internal:80\n/mcp/european-parliament"]

    MCPSetup --> Firewall["🔥 AWF Squid firewall\nAllowlist-only egress"]

    Firewall --> FetchStage["📥 fetch-stage\nEP MCP 1.2.13 + WB MCP 1.0.1 + IMF REST"]

    FetchStage --> EPAvail{"EP available?"}
    EPAvail -->|"status:unavailable"| MCPRetry["🔄 mcp-retry.ts\nExponential backoff"]
    MCPRetry -->|Max retries| DegradeFetch["⚠️ Continue with cached evidence"]
    MCPRetry -->|Recovered| FetchStage
    EPAvail -->|✅ items| EconomicGate{"OR-gate: WB OR IMF?"}
    DegradeFetch --> EconomicGate

    EconomicGate -->|Either OK| Transform["🔄 Stage A: Normalise feeds\nUnavailable-envelope handling"]
    EconomicGate -->|Both fail| AbortEcon["❌ Stage-C completeness fail\n(no economic context)\nAbort PR"]

    Transform --> Analysis["🤖 Stage B: Analysis\nAI-First 2-pass"]

    Analysis --> Pass1["📝 Pass 1 (~60% budget)\nInitial artifact authoring"]
    Pass1 --> Pass2["🔁 Pass 2 (~40% budget)\nRead-back + improve\n≥80w/SWOT, ≥150w/stakeholder,\n≥60% prose, ≥1 Chart.js"]

    Pass2 --> Intel["📄 Emit Stage-B artifacts\nintelligence/ + classification/\n+ risk-scoring/ + threat-assessment/\n(see analysis/templates/)"]

    Intel --> Generate["🏗️ Stage D: Aggregator render\nsrc/aggregator/article-generator.ts\nDeterministic Markdown → 14-lang HTML"]

    Generate --> Output["💾 Stage D: write outputs\nnews/<slug>(-<lang>).{md,html}\n+ Chart.js + JSON-LD + hreflang"]

    Output --> Validator["✅ Stage C: editorial completeness\nreview against 03-analysis-completeness-gate.md"]

    Validator --> LeakScan{"Fallback-leak scan\n(agent-side, see prompts/03)"}
    LeakScan -->|❌ Leak detected| AbortLeak["❌ Abort PR\n[AI_ANALYSIS_REQUIRED] markers present"]

    LeakScan -->|✅ Clean| ThresholdCheck{"Per-artifact line floors\n(reference-quality-thresholds.json)"}
    ThresholdCheck -->|❌ Below| AbortThresh["❌ Abort PR\nInsufficient depth"]

    ThresholdCheck -->|✅ Pass| SafeOutput["📦 Stage E: safe-outputs create-pull-request\nmax-patch-size: 1024 KB (default)\n(news-translate.md: 10240 KB)"]

    SafeOutput --> PR["🔀 PR for human review"]
    PR --> Merge["✅ Merge to main"]

    AbortEcon --> End["🚨 Workflow failed"]
    AbortLeak --> End
    AbortThresh --> End
    Merge --> Deploy["🚀 See Deployment Flow"]

    classDef startNode fill:#4CAF50,stroke:#2E7D32,stroke-width:2px,color:#000000
    classDef compileNode fill:#F48FB1,stroke:#AD1457,stroke-width:2px,color:#000000
    classDef sandboxNode fill:#CE93D8,stroke:#6A1B9A,stroke-width:2px,color:#000000
    classDef checkNode fill:#FFE082,stroke:#F57C00,stroke-width:2px,color:#000000
    classDef analyzeNode fill:#90CAF9,stroke:#1565C0,stroke-width:2px,color:#000000
    classDef errorNode fill:#EF9A9A,stroke:#D32F2F,stroke-width:2px,color:#000000
    classDef validateNode fill:#A5D6A7,stroke:#2E7D32,stroke-width:2px,color:#000000
    classDef outputNode fill:#81C784,stroke:#2E7D32,stroke-width:2px,color:#000000

    class Start startNode
    class Compile,Sandbox compileNode
    class MCPSetup,Firewall sandboxNode
    class EPAvail,EconomicGate,LeakScan,ThresholdCheck checkNode
    class Pass1,Pass2,Intel,Generate analyzeNode
    class AbortEcon,AbortLeak,AbortThresh,End errorNode
    class Validator,Output validateNode
    class SafeOutput,PR,Merge,Deploy outputNode

Note — gh-aw compile is out-of-band: The .lock.yml artifacts executed above are pre-compiled and committed to the repository. Compilation (gh aw compile --validate pinned to GH_AW_VERSION: v0.69.0) runs in the separate .github/workflows/compile-agentic-workflows.yml workflow (manual workflow_dispatch only) and is not part of any scheduled news-generation run. Scheduled news workflows invoke only the already-committed lock files; agent-authored .md edits require a dedicated compile PR before they take effect.

Workflow & Aggregator References:

🤖 Agentic .md sources: .github/workflows/news-*.md
🔒 Compiled lock files: .github/workflows/news-*.lock.yml
🟢 Aggregator entry point: src/aggregator/article-generator.ts
📦 Aggregator modules: src/aggregator/{analysis-aggregator,artifact-order,clean-artifact,markdown-renderer,article-html,article-metadata}.ts
🧠 Methodology library: analysis/methodologies/ (17 methodologies)
📐 Quality thresholds: analysis/methodologies/reference-quality-thresholds.json
⚖️ Stage-C completeness gate: .github/prompts/03-analysis-completeness-gate.md

🌍 Translation Fan-Out Flow (`news-translate`)

The news-translate workflow fans one EN source to 13 non-EN languages (sv da no fi de fr es nl ar he ja ko zh) with an elevated max-patch-size: 10240 KB to accommodate the multi-language PR diff.

flowchart LR
    Trigger["🔔 news-translate trigger\nafter EN article PR merged"] --> PreGate["🛡️ Pre-translation gate\nvalidate-analysis-completeness.js\nScans ALL EN sources"]

    PreGate -->|"❌ Any EN source fails"| Abort["🚫 Abort fan-out"]
    PreGate -->|"✅ All EN pass"| Fanout{"🌐 Per-language fan-out\n13 targets"}

    Fanout --> SV[🇸🇪 sv]
    Fanout --> DA[🇩🇰 da]
    Fanout --> NO[🇳🇴 no]
    Fanout --> FI[🇫🇮 fi]
    Fanout --> DE[🇩🇪 de]
    Fanout --> FR[🇫🇷 fr]
    Fanout --> ES[🇪🇸 es]
    Fanout --> NL[🇳🇱 nl]
    Fanout --> AR[🇸🇦 ar — RTL]
    Fanout --> HE[🇮🇱 he — RTL]
    Fanout --> JA[🇯🇵 ja]
    Fanout --> KO[🇰🇷 ko]
    Fanout --> ZH[🇨🇳 zh]

    SV & DA & NO & FI & DE & FR & ES & NL & AR & HE & JA & KO & ZH --> Validate["✅ axe-core + HTMLHint\nper language"]

    Validate --> Commit["💾 Commit per-language HTML\nbuildSiteFooter() localized"]

    Commit --> PR["📦 safe-outputs create-pull-request\nmax-patch-size: 10240 KB"]

    PR --> Reconciler["🧹 news-translate-reconciler.yml\nCleanup + consolidation"]

    Reconciler --> Done["✅ Multi-language PR ready"]

    style Trigger fill:#4CAF50,stroke:#2E7D32
    style PreGate fill:#90CAF9,stroke:#1565C0
    style Fanout fill:#FFE082,stroke:#F57C00
    style Validate fill:#A5D6A7,stroke:#2E7D32
    style PR fill:#81C784,stroke:#2E7D32
    style Abort fill:#EF9A9A,stroke:#D32F2F

🚀 AWS S3 + CloudFront Deployment Flow

Post-merge, deploy-s3.yml uses GitHub OIDC to assume an AWS role (no long-lived keys) and syncs to S3 with CloudFront invalidation.

flowchart TD
    Merge["🔀 Merge to main"] --> Trigger["🔔 deploy-s3.yml triggered"]

    Trigger --> Prebuild["⚙️ npm run prebuild\n→ generate-news-indexes\n→ generate-sitemap"]

    Prebuild --> Build["🔨 npm run build (tsc)\nTypeScript 6.0.3 compilation"]

    Build --> OIDC["🔐 GitHub OIDC → AWS STS\nAssume S3 deploy role"]

    OIDC --> Sync["📤 aws s3 sync\nUpload changed files only\nVersioned bucket"]

    Sync --> Invalidate["🌐 aws cloudfront create-invalidation\nOnly changed paths\n(minimize billable requests)"]

    Invalidate --> Health["🏥 Health check\nHTTPS + 14-language spot-check"]

    Health -->|"✅ Healthy"| Complete["✅ Deployment complete\neuparliamentmonitor.com live"]
    Health -->|"❌ Failed"| Fallback["🔙 GitHub Pages fallback\nper runbooks/github-pages-failover.md"]

    Fallback --> Alert["📧 Incident created"]

    style Merge fill:#4CAF50,stroke:#2E7D32
    style OIDC fill:#FFE082,stroke:#F57C00
    style Sync fill:#90CAF9,stroke:#1565C0
    style Invalidate fill:#90CAF9,stroke:#1565C0
    style Complete fill:#81C784,stroke:#2E7D32
    style Fallback fill:#FF9800,stroke:#F57C00

📦 npm Publish Flow (Provenance + SLSA 3)

flowchart LR
    Tag["🏷️ git tag v0.8.x"] --> Release["🚀 release.yml"]
    Release --> Semantic["📋 semantic-release\nChangelog + version bump"]
    Semantic --> Build["🔨 npm run build"]
    Build --> SBOM["📄 SPDX SBOM"]
    SBOM --> Attest["🔏 SLSA Level 3 attestation\nGitHub Attestations API"]
    Attest --> Sign["🔐 Sigstore signing"]
    Sign --> Publish["📦 npm publish --provenance"]
    Publish --> Verify["✅ gh attestation verify"]
    Verify --> Done["✅ Published with provenance"]

    style Tag fill:#4CAF50,stroke:#2E7D32
    style Attest fill:#F48FB1,stroke:#AD1457
    style Sign fill:#F48FB1,stroke:#AD1457
    style Publish fill:#81C784,stroke:#2E7D32
    style Done fill:#81C784,stroke:#2E7D32

🔐 Legacy Reference: News Generation Security Flow (pre-agentic)

Preserved for reference. The legacy path below was superseded by the agentic flow above on platform v0.8.x. Kept to document historical control genealogy.

flowchart TD
    Start["🚀 GitHub Actions Trigger\nSchedule: 06:00 UTC\nManual: workflow_dispatch"] --> CheckMCP{"🔌 MCP Server\nAvailable?"}

    CheckMCP -->|"✅ Yes"| ConnectMCP["🔗 Connect to EP MCP Server\nstdio/localhost"]
    CheckMCP -->|"❌ No"| Fallback["⚠️ Use Placeholder Content\nLog Error"]

    ConnectMCP --> RetryCheck{"🔄 Connection\nSuccessful?"}
    RetryCheck -->|"❌ No"| RetryCount{"Retry less than 3?"}
    RetryCount -->|"✅ Yes"| BackoffWait["⏳ Wait 30s\nBetween Retries"]
    BackoffWait --> ConnectMCP
    RetryCount -->|"❌ No"| Fallback

    RetryCheck -->|"✅ Yes"| FetchData["📥 Fetch Parliamentary Data\nPlenary Sessions\nCommittee Meetings\nDocuments, Voting Records"]

    FetchData --> ValidateSchema{"✅ Validate\nJSON Schema?"}
    ValidateSchema -->|"❌ Invalid"| LogError1["📝 Log Validation Error"] --> Fallback
    ValidateSchema -->|"✅ Valid"| SanitizeHTML["🧹 Sanitize HTML"]

    Fallback --> AgentContext
    SanitizeHTML --> AgentContext["🤖 Copilot/LLM Agent\n5 legacy article types"]

    AgentContext --> GenerateEN["📝 Generate English Content"]
    GenerateEN --> Translate["🌍 Translate to 13 languages"]
    Translate --> GenHTML["📄 Generate Article HTML"]
    GenHTML --> CommitPR["📦 Commit and Create PR"]
    CommitPR --> MergePR["🔀 Merge PR"]
    MergePR --> DeployPages["🚀 Deploy to GitHub Pages"]
    DeployPages --> Complete["✅ Generation Complete"]

🔍 Input Validation Security Flow

flowchart TD
    Input["📥 External Input\nEuropean Parliament API\nUntrusted Data"] --> Layer1{"🛡️ Layer 1\nSchema Validation"}

    Layer1 -->|"❌ Invalid Structure"| Reject1["❌ Reject Input\nLog: Invalid JSON\nUse Fallback"]
    Layer1 -->|"✅ Valid Structure"| Layer2{"🛡️ Layer 2\nType Validation"}

    Layer2 -->|"❌ Wrong Types"| Reject2["❌ Reject Input\nLog: Type Mismatch\nUse Fallback"]
    Layer2 -->|"✅ Correct Types"| Layer3{"🛡️ Layer 3\nRange Validation"}

    Layer3 -->|"❌ Out of Bounds"| Reject3["❌ Reject Input\nLog: Range Error\nUse Fallback"]
    Layer3 -->|"✅ Within Bounds"| Layer4{"🛡️ Layer 4\nContent Sanitization"}

    Layer4 --> StripScript["🧹 Strip Script Tags\nRemove script, iframe, object"]
    StripScript --> RemoveEvents["🧹 Remove Event Handlers\nRemove onclick, onerror, onload"]
    RemoveEvents --> ValidateURLs["🔍 Validate URLs\nCheck Protocol\nSanitize Path"]

    ValidateURLs --> Layer5{"🛡️ Layer 5\nHTML Encoding"}

    Layer5 --> EncodeSpecial["🔒 Encode Special Characters\nHTML Entity Encoding"]

    EncodeSpecial --> Layer6{"🛡️ Layer 6\nCSP Compliance"}

    Layer6 --> CheckCSP["✅ Check CSP Headers\nNo Inline Scripts\nNo Eval\nNo External Scripts"]

    CheckCSP -->|"❌ Violation"| Reject4["❌ Block Content\nLog: CSP Violation\nReturn Error"]
    CheckCSP -->|"✅ Compliant"| SafeOutput["✅ Safe Output\nValidated\nSanitized\nEncoded"]

    Reject1 --> FallbackContent["⚠️ Fallback Content\nPlaceholder Articles\nSafe Default"]
    Reject2 --> FallbackContent
    Reject3 --> FallbackContent
    Reject4 --> FallbackContent

    SafeOutput --> DeliverContent["📤 Deliver to Template\nGenerate HTML\nServe to Users"]
    FallbackContent --> DeliverContent

    classDef inputNode fill:#FFE082,stroke:#F57C00,stroke-width:2px,color:#000000
    classDef layerNode fill:#90CAF9,stroke:#1565C0,stroke-width:2px,color:#000000
    classDef sanitizeNode fill:#A5D6A7,stroke:#2E7D32,stroke-width:2px,color:#000000
    classDef rejectNode fill:#EF9A9A,stroke:#D32F2F,stroke-width:2px,color:#000000
    classDef successNode fill:#81C784,stroke:#2E7D32,stroke-width:2px,color:#000000
    classDef fallbackNode fill:#FFF9C4,stroke:#FFA000,stroke-width:2px,color:#000000

    class Input inputNode
    class Layer1,Layer2,Layer3,Layer4,Layer5,Layer6 layerNode
    class StripScript,RemoveEvents,ValidateURLs,EncodeSpecial,CheckCSP sanitizeNode
    class Reject1,Reject2,Reject3,Reject4 rejectNode
    class SafeOutput,DeliverContent successNode
    class FallbackContent fallbackNode

🤖 CI/CD Security Pipeline

flowchart TD
    Trigger[🔔 Git Event<br/>Push to PR<br/>Merge to Main] --> Checkout[📥 Checkout Code<br/>SHA-Pinned Action<br/>actions/checkout@v4]

    Checkout --> SetupNode[⚙️ Setup Node.js 25<br/>SHA-Pinned Action<br/>actions/setup-node@v6]

    SetupNode --> InstallDeps[📦 Install Dependencies<br/>npm ci<br/>Reproducible Build<br/>package-lock.json]

    InstallDeps --> SecurityAudit{🔍 npm audit<br/>Vulnerabilities?}

    SecurityAudit -->|❌ Moderate+| AuditFail[❌ Security Audit Failed<br/>Block PR Merge<br/>Create Issue]
    SecurityAudit -->|✅ None/Low| Lint[🔍 ESLint<br/>Security Rules<br/>Code Quality<br/>Complexity Check]

    Lint -->|❌ Errors| LintFail[❌ Lint Failed<br/>Block PR Merge<br/>Show Errors]
    Lint -->|✅ Pass| Format[✨ Prettier Check<br/>Code Formatting<br/>Consistency]

    Format -->|❌ Not Formatted| FormatFail[❌ Format Failed<br/>Run: npm run format<br/>Commit Changes]
    Format -->|✅ Formatted| HTMLHint[📄 HTMLHint<br/>HTML Validation<br/>Standards Compliance]

    HTMLHint -->|❌ Errors| HTMLFail[❌ HTML Failed<br/>Fix Issues<br/>Re-validate]
    HTMLHint -->|✅ Pass| UnitTests[🧪 Unit Tests<br/>87 Tests<br/>Vitest]

    UnitTests -->|❌ Fail| TestFail[❌ Tests Failed<br/>Block PR Merge<br/>Debug Failures]
    UnitTests -->|✅ Pass| IntegrationTests[🔗 Integration Tests<br/>82 Tests<br/>MCP Client Tests]

    IntegrationTests -->|❌ Fail| TestFail
    IntegrationTests -->|✅ Pass| Coverage{📊 Code Coverage<br/>&gt; 80% Lines?<br/>&gt; 75% Branches?}

    Coverage -->|❌ Below Threshold| CoverageFail[❌ Coverage Failed<br/>Add Tests<br/>Meet Threshold]
    Coverage -->|✅ Above Threshold| CodeQL[🔒 CodeQL SAST<br/>Security Analysis<br/>Vulnerability Detection]

    CodeQL -->|❌ Findings| CodeQLFail[❌ CodeQL Failed<br/>Critical/High Issues<br/>Fix Vulnerabilities]
    CodeQL -->|✅ Clean| BuildCheck[🏗️ Build Check<br/>News Generation<br/>Index Generation<br/>Sitemap Generation]

    BuildCheck -->|❌ Fail| BuildFail[❌ Build Failed<br/>Check Logs<br/>Fix Errors]
    BuildCheck -->|✅ Pass| Approve[✅ All Checks Passed<br/>Ready to Merge<br/>Deploy on Merge]

    AuditFail --> End[❌ Pipeline Failed]
    LintFail --> End
    FormatFail --> End
    HTMLFail --> End
    TestFail --> End
    CoverageFail --> End
    CodeQLFail --> End
    BuildFail --> End
    Approve --> End[✅ Pipeline Success]

    style Trigger fill:#e8f5e9
    style SecurityAudit fill:#ffe1e1
    style Lint fill:#e1f5ff
    style Format fill:#e1f5ff
    style HTMLHint fill:#e1f5ff
    style UnitTests fill:#e8f5e9
    style IntegrationTests fill:#e8f5e9
    style Coverage fill:#e1f5ff
    style CodeQL fill:#ffe1e1
    style BuildCheck fill:#e8f5e9
    style Approve fill:#d4edda
    style End fill:#d4edda
    style AuditFail fill:#ffe1e1
    style LintFail fill:#ffe1e1
    style TestFail fill:#ffe1e1
    style CodeQLFail fill:#ffe1e1

🔐 MCP Client Connection Security Flow

flowchart TD
    Start[🚀 Initialize MCP Client<br/>Connection Parameters<br/>Retry Config] --> CheckEnv{🔍 Check Environment<br/>USE_EP_MCP?}

    CheckEnv -->|❌ Disabled| DisabledMode[⚠️ MCP Disabled<br/>Skip Connection<br/>Use Fallback]
    CheckEnv -->|✅ Enabled| AttemptCount{🔄 Attempt Count<br/>< Max Attempts?}

    AttemptCount -->|❌ Exceeded| MaxRetries[❌ Max Retries Reached<br/>Log Error<br/>Use Fallback]
    AttemptCount -->|✅ Within Limit| SpawnProcess[⚙️ Spawn MCP Process<br/>npx european-parliament-mcp-server<br/>stdio: pipe]

    SpawnProcess --> WaitConnection[⏳ Wait for Ready<br/>Startup Delay: 500ms<br/>Monitor stderr]

    WaitConnection --> ConnectionCheck{✅ Connection<br/>Established?}

    ConnectionCheck -->|❌ Timeout| IncrementRetry[🔄 Increment Counter<br/>Calculate Backoff<br/>2^n seconds]
    IncrementRetry --> BackoffWait[⏳ Exponential Backoff<br/>1s → 2s → 4s]
    BackoffWait --> AttemptCount

    ConnectionCheck -->|❌ Process Error| ProcessError[❌ Process Failed<br/>Log stderr<br/>Kill Process]
    ProcessError --> IncrementRetry

    ConnectionCheck -->|✅ Connected| SendHandshake[🤝 Send Initialize Request<br/>JSON-RPC 2.0<br/>List Available Tools]

    SendHandshake --> HandshakeCheck{✅ Initialize<br/>Valid?}

    HandshakeCheck -->|❌ Invalid| HandshakeFail[❌ Initialize Failed<br/>Protocol Mismatch<br/>Close Connection]
    HandshakeFail --> IncrementRetry

    HandshakeCheck -->|✅ Valid| Authenticated[✅ Connection Ready<br/>Reset Retry Counter<br/>Log Success]

    Authenticated --> RequestLoop[🔁 Request Loop<br/>Send Requests<br/>60s Timeout Per Request]

    RequestLoop --> ValidateResponse{✅ Validate<br/>Response?}

    ValidateResponse -->|❌ Invalid| ResponseError[❌ Invalid Response<br/>Log Error<br/>Retry Request]
    ResponseError --> RetryRequest{Retry < 3?}
    RetryRequest -->|✅ Yes| RequestLoop
    RetryRequest -->|❌ No| UseCached[⚠️ Use Cached Data<br/>Or Fallback]

    ValidateResponse -->|✅ Valid| ProcessData[✅ Process Data<br/>Parse Response<br/>Extract Fields]

    DisabledMode --> End[🎯 Complete]
    MaxRetries --> End
    UseCached --> End
    ProcessData --> End

    style Start fill:#e8f5e9
    style CheckEnv fill:#fff4e1
    style AttemptCount fill:#e1f5ff
    style SpawnProcess fill:#e8f5e9
    style ConnectionCheck fill:#e1f5ff
    style HandshakeCheck fill:#e1f5ff
    style ValidateResponse fill:#e1f5ff
    style Authenticated fill:#d4edda
    style ProcessData fill:#d4edda
    style DisabledMode fill:#fff3cd
    style MaxRetries fill:#ffe1e1
    style ProcessError fill:#ffe1e1
    style HandshakeFail fill:#ffe1e1
    style ResponseError fill:#ffe1e1
    style End fill:#d4edda

📊 Content Delivery Security Flow

flowchart LR
    subgraph "User Browser"
        User[👤 User<br/>Browser Request]
    end

    subgraph "GitHub Pages"
        CDN[🌐 GitHub CDN<br/>TLS 1.3<br/>HTTPS Only]
        CACHE[💾 Edge Cache<br/>Static Content<br/>Immutable]
    end

    subgraph "Security Headers"
        HSTS[🔒 HSTS<br/>max-age=31536000<br/>Force HTTPS]
        CSP[🛡️ CSP<br/>default-src 'self'<br/>No Inline Scripts]
        XCTO[🔐 X-Content-Type-Options<br/>nosniff]
        XFO[🚫 X-Frame-Options<br/>DENY]
    end

    subgraph "Static Content"
        HTML[📄 HTML<br/>Validated<br/>Sanitized]
        CSS[🎨 CSS<br/>Inline Styles<br/>No External]
    end

    subgraph "Monitoring"
        LOGS[📝 Access Logs<br/>GitHub Analytics]
        METRICS[📊 Metrics<br/>Requests<br/>Response Time]
    end

    User -->|HTTPS Request| CDN
    CDN -->|Check Cache| CACHE
    CACHE -->|Hit| Return
    CACHE -->|Miss| Fetch
    Fetch[Fetch from Origin] --> HTML
    HTML --> CSS
    CSS --> Apply_Headers

    Apply_Headers[Apply Security Headers] --> HSTS
    Apply_Headers --> CSP
    Apply_Headers --> XCTO
    Apply_Headers --> XFO

    HSTS --> Return[Return to User]
    CSP --> Return
    XCTO --> Return
    XFO --> Return

    CDN --> LOGS
    Return --> METRICS
    Return --> User

    style User fill:#e1f5ff
    style CDN fill:#f0f0f0
    style CACHE fill:#e8f5e9
    style HSTS fill:#ffe1e1
    style CSP fill:#ffe1e1
    style XCTO fill:#ffe1e1
    style XFO fill:#ffe1e1
    style HTML fill:#e8f5e9
    style CSS fill:#e8f5e9
    style Return fill:#d4edda

🚨 Incident Response Flow

flowchart TD
    Detection[🔔 Incident Detection<br/>Security Alert<br/>Dependabot<br/>CodeQL<br/>User Report] --> Classify{📊 Classify Severity<br/>CVSS Score<br/>Impact Assessment}

    Classify -->|P0 Critical| Critical[🚨 P0: Critical<br/>Repository Compromise<br/>Malicious Content]
    Classify -->|P1 High| High[⚠️ P1: High<br/>XSS Vulnerability<br/>Dependency Issue]
    Classify -->|P2 Medium| Medium[ℹ️ P2: Medium<br/>Data Integrity<br/>Workflow Failure]
    Classify -->|P3 Low| Low[📝 P3: Low<br/>Documentation<br/>Non-Critical Bug]

    Critical --> ImmediateResponse[⚡ Immediate Response<br/>Disable Workflows<br/>Revert Commits<br/>Notify Team]
    High --> UrgentResponse[🔥 Urgent Response<br/>Create Security Advisory<br/>Block PR Merges]
    Medium --> StandardResponse[📋 Standard Response<br/>Create Issue<br/>Schedule Fix]
    Low --> RoutineResponse[📌 Routine Response<br/>Add to Backlog<br/>Next Sprint]

    ImmediateResponse --> Contain[🔒 Containment<br/>Remove Malicious Content<br/>Isolate Compromised Code<br/>Revoke Tokens]
    UrgentResponse --> Contain
    StandardResponse --> Contain
    RoutineResponse --> Contain

    Contain --> Investigate[🔍 Investigation<br/>Review Git Logs<br/>Check Actions Logs<br/>Analyze CodeQL Findings]

    Investigate --> RootCause{🎯 Root Cause<br/>Identified?}

    RootCause -->|❌ No| DeepDive[🔬 Deep Analysis<br/>Forensics<br/>External Review]
    DeepDive --> RootCause

    RootCause -->|✅ Yes| Remediate[🔧 Remediation<br/>Apply Patches<br/>Update Dependencies<br/>Fix Vulnerabilities]

    Remediate --> Test[🧪 Testing<br/>Unit Tests<br/>Integration Tests<br/>Security Scans]

    Test -->|❌ Fail| FixIssues[🛠️ Fix Issues<br/>Debug<br/>Re-apply Fixes]
    FixIssues --> Remediate

    Test -->|✅ Pass| Deploy[🚀 Deploy Fix<br/>Merge PR<br/>GitHub Actions<br/>Update Documentation]

    Deploy --> Verify[✅ Verification<br/>Monitor Metrics<br/>Check Logs<br/>Confirm Resolution]

    Verify -->|❌ Not Resolved| Escalate[⬆️ Escalate<br/>Senior Review<br/>External Help]
    Escalate --> Investigate

    Verify -->|✅ Resolved| Document[📝 Documentation<br/>Incident Report<br/>Lessons Learned<br/>Update Threat Model]

    Document --> Communicate[📢 Communication<br/>Security Advisory<br/>CHANGELOG.md<br/>Close Issue]

    Communicate --> PostMortem[🔄 Post-Mortem<br/>Team Review<br/>Process Improvements<br/>Update Procedures]

    PostMortem --> Complete[✅ Incident Closed<br/>Controls Updated<br/>Metrics Recorded]

    style Detection fill:#fff4e1
    style Critical fill:#ffe1e1
    style High fill:#fff3cd
    style Medium fill:#e1f5ff
    style Low fill:#f0f0f0
    style Contain fill:#e8f5e9
    style Remediate fill:#e8f5e9
    style Deploy fill:#e8f5e9
    style Complete fill:#d4edda

🛡️ Vulnerability Management Workflow

This workflow implements ISO 27001:2022 Control A.8.8 (Management of Technical Vulnerabilities) with defined severity levels and SLA-based remediation timelines.

flowchart TD
    Discovery[🔍 Vulnerability Discovery] --> Source{Discovery<br/>Source}
    
    Source -->|Dependabot| DepAlert[🤖 Dependabot Alert<br/>Dependencies<br/>GitHub Security]
    Source -->|CodeQL| CodeQLAlert[🔒 CodeQL Finding<br/>SAST Scanning<br/>Security Issue]
    Source -->|npm audit| AuditAlert[📦 npm audit<br/>Package Vulnerabilities<br/>CVE Database]
    Source -->|Manual| ManualReport[👤 Manual Report<br/>Security Researcher<br/>User Report]
    
    DepAlert --> Assess
    CodeQLAlert --> Assess
    AuditAlert --> Assess
    ManualReport --> Assess
    
    Assess[📊 Assessment Phase] --> CVSSScore{🎯 CVSS Score<br/>Calculation}
    
    CVSSScore --> Exploit{🔬 Exploitability<br/>Analysis}
    Exploit --> Impact{💥 Impact<br/>Assessment}
    
    Impact --> Prioritize{⚡ Prioritization}
    
    Prioritize -->|Critical 9.0-10.0| Critical[🚨 P0: Critical<br/>SLA: 24 hours<br/>Remote Code Execution<br/>Data Breach Risk]
    Prioritize -->|High 7.0-8.9| High[⚠️ P1: High<br/>SLA: 7 days<br/>Privilege Escalation<br/>XSS/CSRF]
    Prioritize -->|Medium 4.0-6.9| Medium[ℹ️ P2: Medium<br/>SLA: 30 days<br/>Information Disclosure<br/>DoS]
    Prioritize -->|Low 0.1-3.9| Low[📝 P3: Low<br/>SLA: 90 days<br/>Minor Issues<br/>Low Impact]
    
    Critical --> EmergencyTeam[🚨 Emergency Response<br/>Notify Security Team<br/>Disable Affected Feature]
    High --> UrgentAction[🔥 Urgent Action<br/>Create Security Advisory<br/>Block Deployments]
    Medium --> StandardTrack[📋 Standard Track<br/>Create Issue<br/>Schedule Sprint]
    Low --> BacklogAdd[📌 Backlog<br/>Log for Future<br/>Next Release]
    
    EmergencyTeam --> Remediation
    UrgentAction --> Remediation
    StandardTrack --> Remediation
    BacklogAdd --> Remediation
    
    Remediation[🔧 Remediation Strategy] --> Strategy{Strategy<br/>Selection}
    
    Strategy -->|Available| Patch[🩹 Apply Patch<br/>Update Dependency<br/>Upgrade Version]
    Strategy -->|Not Available| Workaround[🔀 Implement Workaround<br/>Code Changes<br/>Configuration Update]
    Strategy -->|Not Feasible| Mitigate[🛡️ Mitigate Risk<br/>Additional Controls<br/>Monitoring]
    Strategy -->|False Positive| Accept[✅ Accept Risk<br/>Document Rationale<br/>Security Exception]
    
    Patch --> Testing
    Workaround --> Testing
    Mitigate --> Testing
    Accept --> Document
    
    Testing[🧪 Verification Testing] --> UnitTest[✅ Unit Tests<br/>169 Tests Pass]
    UnitTest --> IntegTest[🔗 Integration Tests<br/>82 Tests Pass]
    IntegTest --> SecScan[🔒 Security Scan<br/>CodeQL Clean<br/>npm audit Clean]
    
    SecScan --> TestResult{Tests<br/>Pass?}
    TestResult -->|❌ Fail| FixFailed[🛠️ Fix Failed Tests<br/>Debug Issues<br/>Adjust Fix]
    FixFailed --> Remediation
    
    TestResult -->|✅ Pass| Deploy[🚀 Deploy Fix<br/>Merge PR<br/>Production Release]
    
    Deploy --> Verify[✅ Post-Deploy Verification] --> Rescan{Vulnerability<br/>Resolved?}
    
    Rescan -->|❌ Not Fixed| Escalate[⬆️ Escalate<br/>Senior Security Review<br/>External Consultation]
    Escalate --> Remediation
    
    Rescan -->|✅ Fixed| Document[📝 Documentation]
    
    Document --> UpdateAdvisory[📄 Update Security Advisory<br/>CVE Details<br/>Remediation Steps]
    UpdateAdvisory --> UpdateCHANGELOG[📋 Update CHANGELOG.md<br/>Security Fix Entry<br/>Version Bump]
    UpdateCHANGELOG --> CloseIssue[🔒 Close Issue<br/>Link to Commit<br/>Verification Evidence]
    
    CloseIssue --> Metrics[📊 Update Metrics<br/>MTTR Calculation<br/>Vulnerability Stats]
    
    Metrics --> Review[🔄 Post-Fix Review<br/>Lessons Learned<br/>Process Improvement]
    
    Review --> Complete[✅ Vulnerability Closed<br/>Evidence Recorded<br/>Controls Updated]
    
    style Discovery fill:#fff4e1
    style Critical fill:#ffe1e1
    style High fill:#fff3cd
    style Medium fill:#e1f5ff
    style Low fill:#f0f0f0
    style Patch fill:#e8f5e9
    style Testing fill:#e1f5ff
    style Deploy fill:#e8f5e9
    style Complete fill:#d4edda
    style Accept fill:#fff3cd

Vulnerability Management Security Controls

Phase	Control	SLA	ISMS Reference
Discovery	Automated scanning (Dependabot, CodeQL, npm audit)	Continuous	ISO 27001 A.8.8
Assessment	CVSS scoring, exploitability analysis	24 hours	NIST SP 800-30
Prioritization	Risk-based tiers with SLAs	By severity	ISO 27001 A.5.9
Remediation	Patch/workaround/mitigate/accept	24h-90d	ISO 27001 A.8.8
Verification	Testing, scanning, deployment validation	Before close	ISO/IEC 27001:2013 A.14.2.8
Documentation	Advisories, CHANGELOG, evidence	Required	ISO/IEC 27001:2013 A.12.1.1
Metrics	MTTR, vulnerability stats tracking	Monthly	ISO/IEC 27001:2013 A.18.2.1

Mean Time to Remediate (MTTR) Targets:

Critical (P0): 24 hours
High (P1): 7 days
Medium (P2): 30 days
Low (P3): 90 days

🔗 MCP Data Integration Security Flow

This flow shows the end-to-end secure data pipeline from European Parliament APIs through the MCP server to static site generation, with comprehensive security controls at each stage.

flowchart TD
    subgraph "European Parliament APIs"
        EPAPI["🏛️ EP Official APIs\nMEPs, Sessions\nDocuments, Votes"]
    end
    
    subgraph "MCP Server Layer"
        MCPServer["⚙️ EP MCP Server\neuropean-parliament-mcp-server\nNode.js 25"]
        MCPTransport["📡 JSON-RPC 2.0\nstdio Transport\nProtocol v1.0"]
        MCPCache["💾 LRU Cache\nTTL: 5 min\nMax: 500 entries"]
    end
    
    subgraph "Client Layer"
        MCPClient["🔌 MCP Client\nCustom JSON-RPC over stdio\nsrc/mcp/ep-mcp-client.ts"]
        SchemaVal["🧪 Planned: Schema Validation\nJSON Schema\nType Checking"]
        TypeCheck["🔍 Planned: Type Validation\nTypeScript Interfaces\nRuntime Checks"]
    end
    
    subgraph "Sanitization Pipeline"
        HTMLSan["🧹 Planned: HTML Sanitizer\nDOMPurify\nStrip Scripts"]
        XSSEncode["🔒 Planned: XSS Encoding\nHTML Entities"]
        URLVal["🔗 Planned: URL Validation\nHTTPS Only\nDomain Whitelist"]
        LengthCheck["📏 Planned: Length Validation\nMax Lengths\nTruncation"]
    end
    
    subgraph "Content Generation"
        Template["📄 Template Engine\n14 Languages\nHTML5"]
        CSPCheck["🛡️ CSP Compliance\nJSON-LD Allowed\nNo eval"]
        HTMLVal["✅ HTML Validation\nhtmlhint\nStandards Check"]
    end
    
    subgraph "Output Layer"
        StaticFiles["📦 Static HTML\nindex-LANG.html\nCSS Inline"]
        Sitemap["🗺️ Sitemap.xml\nSEO Optimized\n14 Languages"]
        Deploy["🚀 GitHub Pages\nStatic Site Hosting\nGitHub Actions Deploy"]
    end
    
    subgraph "Error Handling"
        FallbackData["⚠️ Fallback Content\nPlaceholder Articles\nSafe Defaults"]
        ErrorLog["📝 Error Logging\nStructured Logs\nGitHub Actions"]
    end
    
    EPAPI -->|HTTPS Request| MCPServer
    MCPServer --> MCPTransport
    MCPTransport --> MCPCache
    
    MCPCache -->|Cache Hit| ReturnCached["✅ Return Cached\nSkip API Call"]
    MCPCache -->|Cache Miss| FetchFresh["📥 Fetch Fresh\nCall EP API"]
    
    ReturnCached --> MCPClient
    FetchFresh --> MCPClient
    
    MCPClient --> SchemaVal
    SchemaVal -->|"❌ Invalid"| ErrorLog
    SchemaVal -->|"✅ Valid"| TypeCheck
    
    TypeCheck -->|"❌ Invalid"| ErrorLog
    TypeCheck -->|"✅ Valid"| HTMLSan
    
    ErrorLog --> FallbackData
    FallbackData --> Template
    
    HTMLSan --> XSSEncode
    XSSEncode --> URLVal
    URLVal --> LengthCheck
    
    LengthCheck --> Template
    
    Template --> CSPCheck
    CSPCheck -->|"❌ Violation"| ErrorLog
    CSPCheck -->|"✅ Compliant"| HTMLVal
    
    HTMLVal -->|"❌ Invalid"| FixHTML["🔧 Auto-Fix HTML\nCorrect Issues"]
    FixHTML --> HTMLVal
    HTMLVal -->|"✅ Valid"| StaticFiles
    
    StaticFiles --> Sitemap
    Sitemap --> Deploy
    
    Deploy --> CDN["🌐 GitHub CDN\nEdge Caching\nGlobal Distribution"]
    
    classDef apiNode fill:#BBDEFB,stroke:#1565C0,stroke-width:2px,color:#000000
    classDef mcpNode fill:#F0F4C3,stroke:#827717,stroke-width:2px,color:#000000
    classDef clientNode fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px,color:#000000
    classDef sanitizeNode fill:#FFF9C4,stroke:#FFA000,stroke-width:2px,color:#000000
    classDef errorNode fill:#FFCDD2,stroke:#D32F2F,stroke-width:2px,color:#000000
    classDef outputNode fill:#A5D6A7,stroke:#2E7D32,stroke-width:2px,color:#000000
    classDef deployNode fill:#81C784,stroke:#2E7D32,stroke-width:2px,color:#000000

    class EPAPI apiNode
    class MCPServer,MCPTransport,MCPCache mcpNode
    class MCPClient,SchemaVal,TypeCheck clientNode
    class HTMLSan,XSSEncode,URLVal,LengthCheck sanitizeNode
    class FallbackData,ErrorLog errorNode
    class Template,CSPCheck,HTMLVal,StaticFiles,Sitemap outputNode
    class Deploy,CDN deployNode

Data Integration Security Controls

Layer	Control	Purpose	Implementation
API Layer	HTTPS-only communication	Encryption in transit	TLS 1.3, HTTPS-only, HSTS via CDN/hosting config
MCP Server	JSON-RPC 2.0 protocol	Structured communication	Standard protocol implementation
Caching	LRU cache with TTL	Performance + resilience	5 min TTL, 500 entry max
Schema Validation	JSON Schema enforcement (future control)	Data structure integrity	Planned: Ajv validator (strict mode), not yet implemented in codebase
Type Checking	Runtime type validation (future control)	Type safety beyond TypeScript	Planned: io-ts runtime checks, not yet implemented in codebase
HTML Sanitization	Planned: DOMPurify scrubbing (future control)	XSS prevention	Not yet in codebase; current: HTML entity encoding via template
XSS Encoding	HTML entity encoding (future control)	Output encoding	Planned: template-level encoding for all user-controlled data, not yet implemented in codebase
URL Validation	HTTPS + whitelist (future control)	Prevent malicious redirects	Planned: HTTPS-only + europarl.europa.eu allowlist for article/source URLs, not yet implemented in codebase
CSP Enforcement	JSON-LD inline scripts allowed; no eval()	XSS mitigation	default-src 'self'; script-src allows type=application/ld+json
HTML Validation	Standards compliance	Cross-browser compatibility	htmlhint, W3C validation
Fallback Content	Graceful degradation	Availability	Placeholder articles
Error Logging	Structured logging	Debugging + monitoring	GitHub Actions logs

🌍 Multi-Language Content Generation Workflow

This workflow illustrates the full CI/CD content generation and validation pipeline for European Parliament news in 14 languages (PR/test-and-report.yml and release.yml). The scheduled daily .github/workflows/news-generation.yml job only runs the generate-and-commit subset (no HTML/SEO/a11y validation loop).

flowchart TD
    Start["🚀 Content Generation\nCI/CD: PRs / Releases\nDaily 06:00 UTC"] --> FetchData["📥 Fetch Source Data\nEP MCP Server\nValidated JSON"]
    
    FetchData --> LangDetect{⚙️ Language Args &<br/>Preset Expansion}
    
    LangDetect --> EN[🇬🇧 English<br/>index.html]
    LangDetect --> SV[🇸🇪 Swedish<br/>index-sv.html]
    LangDetect --> DA[🇩🇰 Danish<br/>index-da.html]
    LangDetect --> NO[🇳🇴 Norwegian<br/>index-no.html]
    LangDetect --> FI[🇫🇮 Finnish<br/>index-fi.html]
    LangDetect --> DE[🇩🇪 German<br/>index-de.html]
    LangDetect --> FR[🇫🇷 French<br/>index-fr.html]
    LangDetect --> ES[🇪🇸 Spanish<br/>index-es.html]
    LangDetect --> NL[🇳🇱 Dutch<br/>index-nl.html]
    LangDetect --> AR[🇸🇦 Arabic<br/>index-ar.html]
    LangDetect --> HE[🇮🇱 Hebrew<br/>index-he.html]
    LangDetect --> JA[🇯🇵 Japanese<br/>index-ja.html]
    LangDetect --> KO[🇰🇷 Korean<br/>index-ko.html]
    LangDetect --> ZH[🇨🇳 Chinese<br/>index-zh.html]
    
    EN --> ENTemplate[📄 EN Template<br/>HTML5 Structure<br/>Semantic Tags]
    SV --> SVTemplate[📄 SV Template<br/>HTML5 Structure<br/>Semantic Tags]
    DA --> DATemplate[📄 DA Template<br/>HTML5 Structure<br/>Semantic Tags]
    NO --> NOTemplate[📄 NO Template<br/>HTML5 Structure<br/>Semantic Tags]
    FI --> FITemplate[📄 FI Template<br/>HTML5 Structure<br/>Semantic Tags]
    DE --> DETemplate[📄 DE Template<br/>HTML5 Structure<br/>Semantic Tags]
    FR --> FRTemplate[📄 FR Template<br/>HTML5 Structure<br/>Semantic Tags]
    ES --> ESTemplate[📄 ES Template<br/>HTML5 Structure<br/>Semantic Tags]
    NL --> NLTemplate[📄 NL Template<br/>HTML5 Structure<br/>Semantic Tags]
    AR --> ARTemplate[📄 AR Template<br/>HTML5 Structure<br/>RTL Support]
    HE --> HETemplate[📄 HE Template<br/>HTML5 Structure<br/>RTL Support]
    JA --> JATemplate[📄 JA Template<br/>HTML5 Structure<br/>Semantic Tags]
    KO --> KOTemplate[📄 KO Template<br/>HTML5 Structure<br/>Semantic Tags]
    ZH --> ZHTemplate[📄 ZH Template<br/>HTML5 Structure<br/>Semantic Tags]
    
    ENTemplate --> ENSecCheck[🔒 EN Security<br/>Sanitize + Validate]
    SVTemplate --> SVSecCheck[🔒 SV Security<br/>Sanitize + Validate]
    DATemplate --> DASecCheck[🔒 DA Security<br/>Sanitize + Validate]
    NOTemplate --> NOSecCheck[🔒 NO Security<br/>Sanitize + Validate]
    FITemplate --> FISecCheck[🔒 FI Security<br/>Sanitize + Validate]
    DETemplate --> DESecCheck[🔒 DE Security<br/>Sanitize + Validate]
    FRTemplate --> FRSecCheck[🔒 FR Security<br/>Sanitize + Validate]
    ESTemplate --> ESSecCheck[🔒 ES Security<br/>Sanitize + Validate]
    NLTemplate --> NLSecCheck[🔒 NL Security<br/>Sanitize + Validate]
    ARTemplate --> ARSecCheck[🔒 AR Security<br/>Sanitize + Validate]
    HETemplate --> HESecCheck[🔒 HE Security<br/>Sanitize + Validate]
    JATemplate --> JASecCheck[🔒 JA Security<br/>Sanitize + Validate]
    KOTemplate --> KOSecCheck[🔒 KO Security<br/>Sanitize + Validate]
    ZHTemplate --> ZHSecCheck[🔒 ZH Security<br/>Sanitize + Validate]
    
    ENSecCheck --> Aggregate
    SVSecCheck --> Aggregate
    DASecCheck --> Aggregate
    NOSecCheck --> Aggregate
    FISecCheck --> Aggregate
    DESecCheck --> Aggregate
    FRSecCheck --> Aggregate
    ESSecCheck --> Aggregate
    NLSecCheck --> Aggregate
    ARSecCheck --> Aggregate
    HESecCheck --> Aggregate
    JASecCheck --> Aggregate
    KOSecCheck --> Aggregate
    ZHSecCheck --> Aggregate
    
    Aggregate[📋 Aggregate Results<br/>14 Language Indexes<br/>Collect Metadata] --> MainIndex[🏠 Generate Main Index<br/>index.html<br/>Language Selector]
    
    MainIndex --> Sitemap[🗺️ Generate Sitemap<br/>sitemap.xml<br/>All 14 Languages]
    
    Sitemap --> ValidateAll{✅ Validate<br/>All Files?}
    
    ValidateAll -->|❌ Validation Errors| ShowErrors[❌ Show Errors<br/>htmlhint Output<br/>Line Numbers]
    ShowErrors --> FixErrors[🔧 Auto-Fix<br/>Common Issues<br/>Re-validate]
    FixErrors --> ValidateAll
    
    ValidateAll -->|✅ All Valid| A11yCheck[♿ Accessibility Check<br/>WCAG 2.1 AA<br/>E2E Workflow Only]
    
    A11yCheck -->|❌ A11y Issues| FixA11y[🔧 Fix A11y<br/>Add lang Attributes<br/>Alt Text]
    FixA11y --> A11yCheck
    
    A11yCheck -->|✅ Compliant| SEOCheck[📊 SEO Validation<br/>Meta Tags<br/>hreflang Links<br/>Release Workflow Only]
    
    SEOCheck --> Complete[✅ Generation Complete<br/>14 Languages<br/>Ready to Deploy]
    
    style Start fill:#e3f2fd
    style LangDetect fill:#fff4e1
    style EN fill:#e8f5e9
    style FR fill:#e8f5e9
    style DE fill:#e8f5e9
    style ES fill:#e8f5e9
    style IT fill:#e8f5e9
    style PT fill:#e8f5e9
    style ENSecCheck fill:#ffe1e1
    style FRSecCheck fill:#ffe1e1
    style DESecCheck fill:#ffe1e1
    style ESSecCheck fill:#ffe1e1
    style ITSecCheck fill:#ffe1e1
    style PTSecCheck fill:#ffe1e1
    style Aggregate fill:#e1f5ff
    style MainIndex fill:#c8e6c9
    style Sitemap fill:#c8e6c9
    style Complete fill:#d4edda

Multi-Language Security Controls

Control	Applied to	Purpose	Standard
HTML Sanitization	All 14 languages	XSS prevention	OWASP ASVS 5.3
HTML Entity Encoding	All 14 languages	Output encoding	OWASP ASVS 5.2
HTML Validation	All 14 languages	Standards compliance	W3C HTML5
Language Attributes	All 14 languages	Accessibility	WCAG 2.1 AA 3.1.1
hreflang Links	All 14 languages	SEO, crawling	Google Guidelines
CSP Headers	All 14 languages	Script execution control	OWASP CSP
Character Encoding	All 14 languages	UTF-8 declaration	HTML5 Standard
Text Direction Handling	All 14 languages (LTR/RTL)	Ensure correct text direction rendering	HTML `dir` attribute / W3C HTML5

Supported Languages:

🇬🇧 English (en) - Primary
🇸🇪 Swedish (sv) - Nordic
🇩🇰 Danish (da) - Nordic
🇳🇴 Norwegian (no) - Nordic
🇫🇮 Finnish (fi) - Nordic
🇩🇪 German (de) - European
🇫🇷 French (fr) - European
🇪🇸 Spanish (es) - European
🇳🇱 Dutch (nl) - European
🇸🇦 Arabic (ar) - RTL
🇮🇱 Hebrew (he) - RTL
🇯🇵 Japanese (ja) - East Asian
🇰🇷 Korean (ko) - East Asian
🇨🇳 Chinese (zh) - East Asian

🚀 Deployment Security Flow

This flow shows the secure deployment pipeline from Git commit to GitHub Pages with comprehensive security gates, SBOM generation, and SLSA attestations. Note: linting, testing, and coverage gates apply to PR merges and release workflows; the daily news-generation workflow triggers GitHub Pages deployment directly after build.

flowchart TD
    Commit[💾 Git Commit<br/>Developer Push<br/>Feature Branch] --> SHAVerify[🔐 SHA Verification<br/>Git Integrity Check<br/>GPG Signature]
    
    SHAVerify --> GHActions[🤖 GitHub Actions<br/>Workflow Trigger<br/>ubuntu-latest]
    
    GHActions --> SecGates[🛡️ Security Gates<br/>PR & Release Workflows] --> Gate1{Gate 1:<br/>Linting}
    
    Gate1 -->|❌ Fail| BlockDeploy1[🚫 Block PR / Release<br/>ESLint Errors<br/>Fix Required]
    Gate1 -->|✅ Pass| Gate2{Gate 2:<br/>Unit Tests}
    
    Gate2 -->|❌ Fail| BlockDeploy2[🚫 Block PR / Release<br/>169 Tests Failed<br/>Debug Required]
    Gate2 -->|✅ Pass| Gate3{Gate 3:<br/>Integration Tests}
    
    Gate3 -->|❌ Fail| BlockDeploy3[🚫 Block PR / Release<br/>82 Tests Failed<br/>Fix Required]
    Gate3 -->|✅ Pass| Gate4{Gate 4:<br/>Security Scan}
    
    Gate4 -->|❌ Critical/High| BlockDeploy4[🚫 Block PR / Release<br/>CodeQL Issues<br/>Vulnerability Fix]
    Gate4 -->|✅ Pass| Gate5{Gate 5:<br/>Coverage}
    
    Gate5 -->|❌ Below 80%| BlockDeploy5[🚫 Block PR / Release<br/>Coverage Too Low<br/>Add Tests]
    Gate5 -->|✅ Pass| Build[🏗️ Build Phase]
    
    Build --> GenNews[📰 Generate News<br/>14 Languages<br/>All Article Types]
    GenNews --> GenIndex[📋 Generate Indexes<br/>Language Indexes<br/>Main Index]
    GenIndex --> GenSitemap[🗺️ Generate Sitemap<br/>sitemap.xml<br/>SEO Optimization]
    
    GenSitemap --> SBOM[📦 SBOM Generation<br/>SPDX Format<br/>All Dependencies]
    
    SBOM --> Attest1[🔏 Build Provenance<br/>SLSA Level 3<br/>GitHub Attestations]
    Attest1 --> Attest2[🔐 SBOM Attestation<br/>Cryptographic Sign<br/>Sigstore]
    
    Attest2 --> Artifacts[📦 Collect Artifacts<br/>HTML Files<br/>CSS Files<br/>Sitemap<br/>SBOM]
    
    Artifacts --> DeployPrep[🚀 Deployment Prep<br/>Organize Files<br/>Check Integrity]
    
    DeployPrep --> DeployGHP[📤 Deploy to GitHub Pages<br/>Static Files<br/>actions/deploy-pages]
    
    DeployGHP --> GHPages[🌐 GitHub Pages Live<br/>GitHub CDN<br/>Global Distribution]
    
    GHPages --> HealthCheck{🏥 Health Check<br/>Site Accessible?}
    
    HealthCheck -->|❌ Failed| Rollback[🔙 Rollback<br/>Revert to Previous<br/>Restore Last Good]
    Rollback --> NotifyFailure[📧 Notify Team<br/>Deployment Failed<br/>Incident Created]
    
    HealthCheck -->|✅ Success| Verify[✅ Verification Phase] --> CheckHTTPS{HTTPS<br/>Working?}
    
    CheckHTTPS -->|❌ No| Rollback
    CheckHTTPS -->|✅ Yes| CheckContent{Content<br/>Loads?}
    
    CheckContent -->|❌ No| Rollback
    CheckContent -->|✅ Yes| CheckLangs{All 14<br/>Languages?}
    
    CheckLangs -->|❌ Missing| Rollback
    CheckLangs -->|✅ Present| CheckSitemap{Sitemap<br/>Valid?}
    
    CheckSitemap -->|❌ Invalid| Rollback
    CheckSitemap -->|✅ Valid| UpdateMetrics[📊 Update Metrics<br/>Deployment Time<br/>Build Duration<br/>Success Rate]
    
    UpdateMetrics --> TagRelease[🏷️ Tag Release<br/>Git Tag<br/>Version Bump<br/>Create GitHub Release]
    
    TagRelease --> NotifySuccess[📧 Notify Team<br/>Deployment Successful<br/>Version + URL]
    
    NotifySuccess --> Complete[✅ Deployment Complete<br/>Live on GitHub Pages<br/>Attested + Verified]
    
    style Commit fill:#e3f2fd
    style SHAVerify fill:#ffe1e1
    style Gate1 fill:#e1f5ff
    style Gate2 fill:#e1f5ff
    style Gate3 fill:#e1f5ff
    style Gate4 fill:#ffe1e1
    style Gate5 fill:#e1f5ff
    style BlockDeploy1 fill:#ffcdd2
    style BlockDeploy2 fill:#ffcdd2
    style BlockDeploy3 fill:#ffcdd2
    style BlockDeploy4 fill:#ffcdd2
    style BlockDeploy5 fill:#ffcdd2
    style SBOM fill:#fff9c4
    style Attest1 fill:#ffe1e1
    style Attest2 fill:#ffe1e1
    style DeployGHP fill:#c8e6c9
    style GHPages fill:#e8f5e9
    style Rollback fill:#ffcdd2
    style Complete fill:#d4edda

Deployment Security Controls

Stage	Control	Purpose	Implementation
Commit	SHA verification, GPG signatures	Code integrity	Git built-in
Linting	ESLint security rules	Code quality, vulnerabilities	eslint-plugin-security
Unit Tests	169 tests, 82%+ coverage	Functional correctness	Vitest
Integration Tests	82 MCP client tests	API contract validation	Vitest + custom JSON-RPC MCP client
Security Scan	CodeQL SAST	Vulnerability detection	GitHub CodeQL
Coverage Gate	80% lines, 75% branches	Test thoroughness	Vitest v8 provider (@vitest/coverage-v8)
SBOM	SPDX JSON format	Supply chain transparency	Anchore SBOM Action
Provenance	SLSA Level 3	Build integrity	GitHub Attestations
Attestation	Cryptographic signing	Artifact authenticity	Sigstore
Health Check	Multi-point verification	Deployment validation	Custom checks
Rollback	Automated revert	Failure recovery	Git + GitHub Pages re-deploy
Metrics	Deployment tracking	Performance monitoring	GitHub Actions logs

Deployment Security Requirements:

✅ All security gates must pass (no critical/high vulnerabilities)
✅ SBOM generated and attested for every deployment
✅ SLSA Level 3 provenance attestation required
✅ Health checks must pass before declaring success
✅ Automatic rollback on any verification failure
✅ Team notification on success/failure
✅ Deployment metrics recorded for audit trail

🚀 Release Workflow with Documentation Automation

This comprehensive flow shows the automated release process with SLSA Level 3 attestations and documentation-as-code implementation.

flowchart TD
    Start[🚀 Release Trigger<br/>Manual or Tag Push] --> Prepare[📋 Prepare Job]

    Prepare --> Lint[🔍 Run Linter<br/>ESLint Validation]
    Lint --> HTMLVal[✅ Validate HTML<br/>htmlhint]
    HTMLVal --> Coverage[📊 Run Tests with Coverage<br/>169 Unit Tests<br/>82%+ Coverage]

    Coverage --> CoverageCheck{Coverage<br/>Thresholds?}
    CoverageCheck -->|❌ Fail| Fail1[❌ Build Failed]
    CoverageCheck -->|✅ Pass| E2E[🎭 Run E2E Tests<br/>Playwright Chromium]

    E2E --> E2ECheck{E2E Tests<br/>Pass?}
    E2ECheck -->|❌ Fail| Fail2[❌ Build Failed]
    E2ECheck -->|✅ Pass| CleanDocs[🧹 Clean Old Documentation<br/>Remove docs/api, coverage, test-results]

    CleanDocs --> GenAPI[📖 Generate API Documentation<br/>JSDoc → docs/api/<br/>52 files]
    GenAPI --> CopyReports[📋 Copy Test Reports<br/>Coverage → docs/coverage/<br/>Test Results → docs/test-results/]

    CopyReports --> GenIndex[🎨 Generate Documentation Index<br/>Beautiful Hub Page<br/>docs/index.html]

    GenIndex --> VerifyDocs{Verify<br/>Documentation<br/>Structure?}
    VerifyDocs -->|❌ Missing Files| Fail3[❌ Build Failed]
    VerifyDocs -->|✅ Complete| CommitDocs[💾 Commit Documentation<br/>Git Auto-Commit<br/>To Main Branch]

    CommitDocs --> TagVersion{Workflow<br/>Dispatch?}
    TagVersion -->|✅ Yes| CreateTag[🏷️ Create Version Tag<br/>npm version + git tag]
    TagVersion -->|❌ No| Build[🔨 Build Job]
    CreateTag --> Build

    Build --> Checkout2[📥 Checkout at Tag]
    Checkout2 --> GenNews{News<br/>Directory<br/>Empty?}
    GenNews -->|✅ Yes| SampleNews[📰 Generate Sample News<br/>Week Ahead Articles]
    GenNews -->|❌ No| CreateArtifact
    SampleNews --> CreateArtifact[📦 Create Release Artifacts<br/>Include docs/, playwright-report/<br/>ZIP Archive]

    CreateArtifact --> GenSBOM[🔐 Generate SBOM<br/>SPDX JSON Format<br/>Anchore SBOM Action]
    GenSBOM --> BuildProv[📜 Build Provenance Attestation<br/>SLSA Level 3<br/>GitHub Attestations API]
    BuildProv --> SBOMAttest[🔏 SBOM Attestation<br/>Cryptographic Signing]

    SBOMAttest --> UploadArtifacts[📤 Upload All Artifacts<br/>Build + Security Artifacts]

    UploadArtifacts --> Release[🚀 Release Job]
    Release --> DraftNotes[📝 Draft Release Notes<br/>Release Drafter]
    DraftNotes --> CreateRelease[🎉 Create GitHub Release<br/>Attach All Artifacts]

    CreateRelease --> Verify{Verification<br/>Required?}
    Verify -->|✅ Yes| VerifyCmd[🔍 Verify Attestations<br/>gh attestation verify]
    Verify -->|❌ No| Complete[✅ Release Complete<br/>Documentation Published<br/>Artifacts Attested]
    VerifyCmd --> Complete

    style Start fill:#e3f2fd
    style Prepare fill:#f0f4c3
    style Lint fill:#e1f5ff
    style Coverage fill:#e1f5ff
    style E2E fill:#e1f5ff
    style CleanDocs fill:#fff9c4
    style GenAPI fill:#c8e6c9
    style CopyReports fill:#c8e6c9
    style GenIndex fill:#c8e6c9
    style CommitDocs fill:#a5d6a7
    style Build fill:#f0f4c3
    style GenSBOM fill:#ffe1e1
    style BuildProv fill:#ffe1e1
    style SBOMAttest fill:#ffe1e1
    style Release fill:#f0f4c3
    style CreateRelease fill:#c5cae9
    style Complete fill:#c8e6c9
    style Fail1 fill:#ffcdd2
    style Fail2 fill:#ffcdd2
    style Fail3 fill:#ffcdd2

Release Workflow Security Controls

Stage	Control	Purpose	ISMS Reference
Validation	Linter + HTML validation	Code quality, syntax errors	Quality standards
Testing	169 unit tests, 82%+ coverage	Functional correctness	§3.3 Testing Requirements
E2E Testing	Playwright across browsers	User workflow validation	Quality assurance
Documentation	JSDoc, coverage, E2E reports	Evidence generation	§3.2 Architecture Documentation
Version Control	Git commit + tag	Audit trail, traceability	ISO 27001 A.12.1.1
SBOM Generation	SPDX format, all dependencies	Supply chain transparency	§4.4 Supply Chain Security
Build Provenance	SLSA Level 3 attestation	Build integrity	SLSA Framework
SBOM Attestation	Cryptographic signing	Artifact authenticity	Non-repudiation
Verification	gh attestation verify	Release validation	Trust establishment

Documentation-as-Code Benefits

Integrity:

✅ Generated automatically from code and tests
✅ Version controlled with full git history
✅ Reproducible from any release tag
✅ Part of attested release artifacts

Transparency:

✅ Public access via GitHub Pages
✅ Real-time updates with every release
✅ Complete test coverage visibility
✅ API documentation always current

Compliance:

✅ ISMS §3.2 architecture documentation requirement
✅ ISO 27001 A.12.1.1 documented procedures
✅ Audit trail for all documentation changes
✅ Eliminates documentation drift

ISMS Evidence

Workflow: release.yml
Documentation: docs/index.html
Process Guide: docs/RELEASE_PROCESS.md
Workflow Documentation: WORKFLOWS.md
Attestations: GitHub Attestations
Policy: ISMS Secure Development §3.2

📚 References

Internal Documentation

SECURITY_ARCHITECTURE.md - Security architecture and threat model
WORKFLOWS.md - Current CI/CD workflows
FUTURE_WORKFLOWS.md - Planned enhancements
DATA_MODEL.md - Data structures and schemas
ARCHITECTURE.md - System architecture and C4 models

ISMS Policies (Hack23)

Information Security Policy - Overarching security governance
Secure Development Policy - Secure coding practices
Access Control Policy - Authentication and authorization
Vulnerability Management Policy - Vulnerability handling
Incident Response Policy - Incident management

Standards and Frameworks

ISO 27001:2022 - Information security management
NIST Incident Response (SP 800-61) - Incident handling
NIST CSF 2.0 - Cybersecurity Framework
CIS Controls v8.1 - Security best practices
OWASP Testing Guide - Security testing
OWASP ASVS - Application security verification
SLSA Framework - Supply chain security
GDPR - Data protection regulation
NIS2 Directive - Network and information security

Tools and Technologies

GitHub Actions Security - CI/CD security
CodeQL - Semantic code analysis
Dependabot - Dependency management
Sigstore - Artifact signing
SPDX - Software bill of materials

Document Status: Active
Next Review: 2026-07-20
Owner: Development Team, Hack23 AB
Classification: Public
Version: 1.2

🔄 EU Parliament Monitor — Flowcharts

📚 Architecture Documentation Map

📋 Overview

🛡️ ISMS Policy Alignment

Policy Mapping

Key Security Principles Demonstrated

Compliance Framework Coverage

🔐 News Generation Security Flow

🌍 Translation Fan-Out Flow (`news-translate`)

🚀 AWS S3 + CloudFront Deployment Flow

📦 npm Publish Flow (Provenance + SLSA 3)

🔐 Legacy Reference: News Generation Security Flow (pre-agentic)

🔍 Input Validation Security Flow

🤖 CI/CD Security Pipeline

🔐 MCP Client Connection Security Flow

📊 Content Delivery Security Flow

🚨 Incident Response Flow

🛡️ Vulnerability Management Workflow

Vulnerability Management Security Controls

🔗 MCP Data Integration Security Flow

Data Integration Security Controls

🌍 Multi-Language Content Generation Workflow

Multi-Language Security Controls

🚀 Deployment Security Flow

Deployment Security Controls

🚀 Release Workflow with Documentation Automation

Release Workflow Security Controls

Documentation-as-Code Benefits

ISMS Evidence

📚 References

Internal Documentation

ISMS Policies (Hack23)

Standards and Frameworks

Tools and Technologies

Settings

On This Page

🔄 EU Parliament Monitor — Flowcharts

📚 Architecture Documentation Map

📋 Overview

🛡️ ISMS Policy Alignment

Policy Mapping

Key Security Principles Demonstrated

Compliance Framework Coverage

🔐 News Generation Security Flow

🌍 Translation Fan-Out Flow (news-translate)

🚀 AWS S3 + CloudFront Deployment Flow

📦 npm Publish Flow (Provenance + SLSA 3)

🔐 Legacy Reference: News Generation Security Flow (pre-agentic)

🔍 Input Validation Security Flow

🤖 CI/CD Security Pipeline

🔐 MCP Client Connection Security Flow

📊 Content Delivery Security Flow

🚨 Incident Response Flow

🛡️ Vulnerability Management Workflow

Vulnerability Management Security Controls

🔗 MCP Data Integration Security Flow

Data Integration Security Controls

🌍 Multi-Language Content Generation Workflow

Multi-Language Security Controls

🚀 Deployment Security Flow

Deployment Security Controls

🚀 Release Workflow with Documentation Automation

Release Workflow Security Controls

Documentation-as-Code Benefits

ISMS Evidence

📚 References

Internal Documentation

ISMS Policies (Hack23)

Standards and Frameworks

Tools and Technologies

Settings

On This Page

🌍 Translation Fan-Out Flow (`news-translate`)