Skip to content

STATEDIAGRAM.md

Latest commit

 

History

History
1393 lines (1072 loc) · 57.3 KB

STATEDIAGRAM.md

File metadata and controls

1393 lines (1072 loc) · 57.3 KB

Hack23 Logo

🔄 EU Parliament Monitor — State Diagrams

📊 System State Transitions and Lifecycle Management
🎯 Behavioral Model for Static News Generation Platform

Owner Version Effective Date Review Cycle

📋 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
🏷️ Classification: Public (Open Source European Parliament Monitoring Platform)

📚 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

🛡️ ISMS Policy Alignment

This state diagram documentation implements controls aligned with Hack23 AB's publicly available ISMS framework.

Applicable ISMS Policies

Policy Relevance
Secure Development Policy State management follows secure SDLC lifecycle
Information Security Policy System state transitions comply with security governance
Incident Response Plan Error and failure states trigger incident response procedures
Change Management Policy Deployment state transitions follow change management process

📋 Overview

This document defines all state transitions and lifecycles in the EU Parliament Monitor system. State diagrams capture behavioral aspects that complement the structural views (C4 model), data views (ERD), and process flows (flowcharts).

Purpose

State diagrams serve to:

  1. Define Valid State Transitions: Document legal state changes and their triggers
  2. Lifecycle Management: Show complete entity lifecycles from creation to archival
  3. Error Handling: Illustrate error states and recovery paths
  4. Concurrency Control: Define states that prevent race conditions
  5. Audit Trail: Enable state-based audit logging and compliance

System Context

EU Parliament Monitor is a static site generator with:

  • Zero Runtime State: No databases, no sessions, no server-side state
  • Build-Time State Machine: All state transitions during GitHub Actions execution
  • Immutable Outputs: Generated artifacts never modified post-creation
  • Idempotent Operations: Repeated executions produce consistent results
  • Graceful Degradation: Fallback states when external dependencies unavailable

🎯 System Lifecycle State

The overall system operates in phases from initialization through publication and monitoring.

stateDiagram-v2
    [*] --> Idle: System Ready

    Idle --> Initializing: Workflow Triggered<br/>(Schedule/Manual)

    Initializing --> ConfigurationLoading: Load Configuration
    ConfigurationLoading --> EnvironmentValidation: Validate Environment
    EnvironmentValidation --> DependencyCheck: Check Dependencies

    DependencyCheck --> DependencyInstall: Missing Dependencies
    DependencyInstall --> DependencyCheck: Retry
    DependencyCheck --> InitializationFailed: Max Retries Exceeded

    DependencyCheck --> Ready: All Dependencies OK

    Ready --> MCPConnection: Connect to Data Sources

    state MCPConnection {
        [*] --> ConnectingMCP
        ConnectingMCP --> MCPConnected: Connection Successful
        ConnectingMCP --> MCPRetrying: Connection Failed
        MCPRetrying --> ConnectingMCP: Backoff Wait
        MCPRetrying --> MCPFallback: Max Retries
        MCPConnected --> [*]
        MCPFallback --> [*]
    }

    MCPConnection --> DataFetching: Data Source Ready

    DataFetching --> Generating: Data Retrieved
    DataFetching --> GeneratingFallback: MCP Unavailable

    Generating --> Validating: Articles Generated
    GeneratingFallback --> Validating: Placeholder Content

    Validating --> Testing: Validation Passed
    Validating --> ValidationFailed: Validation Failed

    ValidationFailed --> Generating: Fix & Retry

    Testing --> TestFailed: Tests Failed
    Testing --> Publishing: Tests Passed

    TestFailed --> [*]: Abort Workflow

    Publishing --> Deployed: Git Push Success
    Publishing --> PublishFailed: Git Push Failed

    PublishFailed --> Publishing: Retry
    PublishFailed --> [*]: Max Retries

    Deployed --> Monitoring: GitHub Pages Deploy

    Monitoring --> Idle: Complete

    InitializationFailed --> [*]: Fatal Error

    note right of Idle
        Waiting for next scheduled
        execution (06:00 UTC) or
        manual workflow_dispatch
    end note

    note right of MCPConnection
        European Parliament MCP Server
        connection with retry logic
        and graceful fallback
    end note

    note right of Deployed
        Static files committed to
        main branch, GitHub Pages
        automatically deploys
    end note
Loading

System State Definitions

State Description Entry Conditions Exit Conditions Timeout
Idle System waiting for trigger Previous workflow complete OR system startup Schedule reached OR manual dispatch N/A
Initializing Loading configuration and environment Workflow triggered Config loaded successfully 30s
ConfigurationLoading Reading package.json, .env files Initialization started Config parsed and validated 10s
EnvironmentValidation Checking environment variables, Node version Config loaded Environment meets requirements 10s
DependencyCheck Verifying npm packages installed Environment validated All deps available OR missing deps identified 15s
DependencyInstall Running npm ci to install packages Missing dependencies detected Installation complete 180s
InitializationFailed Fatal error during startup Repeated failures, missing critical config Workflow terminates N/A
Ready System prepared to execute generation All checks passed Data source connection initiated 5s
MCPConnection Connecting to European Parliament MCP Server Ready state achieved Connected OR fallback mode 30s
DataFetching Retrieving parliamentary data via MCP MCP connected Data retrieved OR fallback 60s
Generating Creating multi-language articles Data available All articles generated 300s
GeneratingFallback Creating placeholder articles MCP unavailable Placeholder articles generated 60s
Validating Running HTML validation, schema checks Generation complete Validation passed OR failed 45s
ValidationFailed Detected invalid output Validation checks failed Retry generation OR abort 10s
Testing Executing ESLint, tests, security scans Validation passed Tests passed OR failed 120s
TestFailed Test suite failures detected Test execution failed Workflow aborted 10s
Publishing Committing and pushing to Git Tests passed Git push successful OR failed 30s
PublishFailed Git push failed Git operation failed Retry OR abort 10s
Deployed Changes pushed to GitHub Git push successful GitHub Pages deployment initiated 5s
Monitoring Awaiting GitHub Pages deployment Deployed Deployment complete 180s

State Transition Rules

Legal Transitions:

  • Forward progression through pipeline stages
  • Retry loops for transient failures (MCP connection, Git push)
  • Fallback paths for graceful degradation (MCP → Fallback content)
  • Error exits to Idle state with notification

Illegal Transitions (prevented by workflow):

  • Cannot skip validation after generation
  • Cannot publish without passing tests
  • Cannot retry indefinitely (max 3 retries for connections)
  • Cannot modify deployed content (immutable artifacts)

📰 Article Lifecycle State

Individual news articles progress through generation, validation, publication, and archival states.

stateDiagram-v2
    [*] --> ArticlePending: Article Scheduled

    ArticlePending --> DataCollecting: Fetch Source Data

    state DataCollecting {
        [*] --> FetchingPlenary
        FetchingPlenary --> FetchingCommittee: Plenary Data OK
        FetchingCommittee --> FetchingDocuments: Committee Data OK
        FetchingDocuments --> FetchingQuestions: Document Data OK
        FetchingQuestions --> DataComplete: Question Data OK

        FetchingPlenary --> DataFetchError: API Error
        FetchingCommittee --> DataFetchError: API Error
        FetchingDocuments --> DataFetchError: API Error
        FetchingQuestions --> DataFetchError: API Error

        DataFetchError --> FetchingPlenary: Retry
        DataFetchError --> DataFallback: Max Retries

        DataComplete --> [*]
        DataFallback --> [*]
    }

    DataCollecting --> ContentGeneration: Data Available

    state ContentGeneration {
        [*] --> TemplateLoading
        TemplateLoading --> LLMPrompting: Template Ready
        LLMPrompting --> ContentReceived: LLM Response OK
        LLMPrompting --> LLMRetry: LLM Error
        LLMRetry --> LLMPrompting: Backoff
        LLMRetry --> PlaceholderContent: Max Retries
        ContentReceived --> [*]
        PlaceholderContent --> [*]
    }

    ContentGeneration --> ArticleDraft: Content Generated

    ArticleDraft --> LanguageProcessing: Process All Languages

    state LanguageProcessing {
        [*] --> ProcessingEN
        ProcessingEN --> ProcessingSV: English OK
        ProcessingSV --> ProcessingDA: Swedish OK
        ProcessingDA --> ProcessingNO: Danish OK
        ProcessingNO --> ProcessingFI: Norwegian OK
        ProcessingFI --> ProcessingDE: Finnish OK
        ProcessingDE --> ProcessingFR: German OK
        ProcessingFR --> ProcessingES: French OK
        ProcessingES --> ProcessingNL: Spanish OK
        ProcessingNL --> ProcessingAR: Dutch OK
        ProcessingAR --> ProcessingHE: Arabic OK
        ProcessingHE --> ProcessingJA: Hebrew OK
        ProcessingJA --> ProcessingKO: Japanese OK
        ProcessingKO --> ProcessingZH: Korean OK
        ProcessingZH --> AllLanguagesComplete: Chinese OK

        ProcessingEN --> LanguageError: Translation Failed
        ProcessingDE --> LanguageError: Translation Failed
        ProcessingFR --> LanguageError: Translation Failed

        LanguageError --> ProcessingEN: Retry Language
        LanguageError --> PartialLanguageSet: Skip Language

        AllLanguagesComplete --> [*]
        PartialLanguageSet --> [*]
    }

    LanguageProcessing --> ArticleValidation: All Languages Processed

    state ArticleValidation {
        [*] --> HTMLValidation
        HTMLValidation --> SchemaValidation: HTML Valid
        SchemaValidation --> ContentValidation: Schema Valid
        ContentValidation --> SecurityValidation: Content Valid
        SecurityValidation --> ValidationComplete: Security OK

        HTMLValidation --> ValidationFailed: Invalid HTML
        SchemaValidation --> ValidationFailed: Invalid Schema
        ContentValidation --> ValidationFailed: Invalid Content
        SecurityValidation --> ValidationFailed: Security Issue

        ValidationComplete --> [*]
        ValidationFailed --> [*]
    }

    ArticleValidation --> ArticleValidated: Validation Passed
    ArticleValidation --> ArticleRejected: Validation Failed

    ArticleRejected --> ArticleDraft: Fix Issues
    ArticleRejected --> ArticleAbandoned: Unfixable

    ArticleValidated --> ArticleStaging: Ready for Publish

    ArticleStaging --> ArticlePublished: Git Commit Success

    ArticlePublished --> ArticleIndexed: Add to Index

    ArticleIndexed --> ArticleLive: GitHub Pages Deploy

    ArticleLive --> ArticleMonitored: Active Monitoring

    ArticleMonitored --> ArticleArchived: 90 Days Old

    ArticleArchived --> [*]: Lifecycle Complete

    ArticleAbandoned --> [*]: Generation Failed

    note right of ArticlePending
        8 article types:
        - Breaking News
        - Week Ahead
        - Week in Review
        - Month Ahead
        - Month in Review
        - Committee Reports
        - Motions
        - Propositions
        Driven by 9 strategy modules in
        src/generators/strategies/
        (1 generic article-strategy +
         8 type-specific strategies)
    end note

    note right of ContentGeneration
        LLM generates article with:
        - Title & subtitle
        - Summary paragraph
        - Detailed analysis
        - Key points
        - Citations
    end note

    note right of LanguageProcessing
        14 languages:
        EN, SV, DA, NO, FI, DE,
        FR, ES, NL, AR, HE, JA,
        KO, ZH
    end note

    note right of ArticleLive
        Immutable content:
        Never modified after
        publication
    end note
Loading

Article State Definitions

State Description Duration Rollback Possible
ArticlePending Article scheduled for generation 0-60s Yes
DataCollecting Fetching source data from EP APIs 10-60s Yes
ContentGeneration LLM creating article content 15-120s Yes
ArticleDraft Initial content created 0-5s Yes
LanguageProcessing Translating to all languages 30-300s Yes
ArticleValidation Running validation checks 10-30s Yes
ArticleRejected Failed validation Until fixed Yes
ArticleAbandoned Permanently failed Permanent No
ArticleValidated Passed all checks 0-5s Yes
ArticleStaging Ready for commit 0-10s Yes
ArticlePublished Committed to Git Permanent No*
ArticleIndexed Added to language indexes Permanent No
ArticleLive Deployed on GitHub Pages Until archived No
ArticleMonitored Active monitoring 90 days No
ArticleArchived Moved to archive Permanent No

*Git history allows reverting, but articles are conceptually immutable.

🔌 MCP Connection State Machine

The Model Context Protocol (MCP) connection manages connectivity to the European Parliament data server.

stateDiagram-v2
    [*] --> Disconnected: System Start

    Disconnected --> Connecting: Initialize Connection

    Connecting --> Authenticating: TCP/Stdio Connected
    Connecting --> ConnectionTimeout: Timeout (10s)

    Authenticating --> Connected: Auth Success
    Authenticating --> AuthFailed: Auth Failed

    ConnectionTimeout --> RetryWait: Transient Error
    AuthFailed --> RetryWait: Retry Auth

    RetryWait --> RetryCount: Backoff Complete

    state RetryCount <<choice>>
    RetryCount --> Connecting: Retry < 3
    RetryCount --> FallbackMode: Retry >= 3

    Connected --> Healthy: Health Check OK

    Healthy --> Active: Ready for Requests

    Active --> RequestSending: Tool Call

    state RequestSending {
        [*] --> SerializingRequest
        SerializingRequest --> SendingData: JSON Ready
        SendingData --> AwaitingResponse: Data Sent
        AwaitingResponse --> ReceivingData: Response Started
        ReceivingData --> DeserializingResponse: Data Complete
        DeserializingResponse --> RequestComplete: Parse OK

        AwaitingResponse --> RequestTimeout: Timeout (30s)
        DeserializingResponse --> RequestError: Parse Error

        RequestComplete --> [*]
        RequestTimeout --> [*]
        RequestError --> [*]
    }

    RequestSending --> Active: Request Success
    RequestSending --> RequestFailed: Request Failed

    RequestFailed --> RetryRequest: Transient Error
    RetryRequest --> RequestSending: Retry

    RequestFailed --> Degraded: Persistent Errors

    Active --> Degraded: Health Check Failed

    Degraded --> Reconnecting: Attempt Recovery

    Reconnecting --> Connected: Reconnect Success
    Reconnecting --> Disconnected: Reconnect Failed

    Connected --> Disconnected: Connection Lost

    Disconnected --> FallbackMode: Max Failures

    FallbackMode --> [*]: Use Placeholder Content

    note right of Disconnected
        MCP server not available:
        - Server not running
        - Network unreachable
        - Configuration error
    end note

    note right of Connected
        MCP protocol handshake
        complete, server ready
        for tool requests
    end note

    note right of Active
        Connection pooling:
        - Reuse connection
        - Keep-alive pings
        - Request queueing
    end note

    note right of FallbackMode
        Graceful degradation:
        Generate articles with
        placeholder content
    end note
Loading

MCP Connection States

State Description Timeout Recovery Action
Disconnected No active connection N/A Initialize connection
Connecting TCP/stdio connection in progress 10s Retry with backoff
Authenticating MCP handshake and auth 5s Retry auth
ConnectionTimeout Connection attempt exceeded timeout N/A Enter retry wait
AuthFailed Authentication rejected N/A Check credentials, retry
RetryWait Exponential backoff delay 1s, 2s, 4s Retry connecting
Connected MCP handshake complete N/A Proceed to health check
Healthy Server health verified N/A Transition to active
Active Ready for tool requests N/A Process requests
RequestSending Tool call in progress 30s Retry on timeout
RequestFailed Request failed N/A Retry or degrade
Degraded Persistent errors detected N/A Attempt reconnection
Reconnecting Attempting to restore connection 10s Reconnect or disconnect
FallbackMode Using placeholder content N/A Continue with fallback

Connection State Rules

Retry Policy:

  • Max 3 connection attempts with exponential backoff (1s, 2s, 4s)
  • Request retries: 2 attempts for transient errors
  • Health checks every 60s when active
  • Automatic reconnection on connection loss

Fallback Triggers:

  • Max connection retries exhausted
  • Persistent authentication failures
  • Server consistently unhealthy
  • Critical tool call failures

✅ Validation State Flow

Data and content validation occurs at multiple stages with different validation rules.

stateDiagram-v2
    [*] --> ValidationQueued: Data/Content Ready

    ValidationQueued --> SchemaValidation: Start Validation

    state SchemaValidation {
        [*] --> CheckStructure
        CheckStructure --> CheckTypes: Structure OK
        CheckTypes --> CheckRequired: Types OK
        CheckRequired --> CheckConstraints: Required OK
        CheckConstraints --> SchemaValid: Constraints OK

        CheckStructure --> SchemaInvalid: Missing Fields
        CheckTypes --> SchemaInvalid: Type Mismatch
        CheckRequired --> SchemaInvalid: Required Missing
        CheckConstraints --> SchemaInvalid: Constraint Violation

        SchemaValid --> [*]
        SchemaInvalid --> [*]
    }

    SchemaValidation --> ContentValidation: Schema Valid
    SchemaValidation --> ValidationFailed: Schema Invalid

    state ContentValidation {
        [*] --> SanitizeHTML
        SanitizeHTML --> RemoveScripts: Strip Dangerous Tags
        RemoveScripts --> RemoveEvents: Remove <script> tags
        RemoveEvents --> EncodeEntities: Remove onX handlers
        EncodeEntities --> ValidateLinks: Encode < > & " '
        ValidateLinks --> CheckLength: Verify URLs
        CheckLength --> ContentValid: Length OK

        CheckLength --> ContentInvalid: Too Long/Short
        ValidateLinks --> ContentInvalid: Broken Links

        ContentValid --> [*]
        ContentInvalid --> [*]
    }

    ContentValidation --> SecurityValidation: Content Valid
    ContentValidation --> ValidationFailed: Content Invalid

    state SecurityValidation {
        [*] --> XSSCheck
        XSSCheck --> SQLInjectionCheck: No XSS
        SQLInjectionCheck --> CSRFCheck: No SQLi
        CSRFCheck --> ClickjackCheck: No CSRF
        ClickjackCheck --> SecurityValid: No Clickjack

        XSSCheck --> SecurityInvalid: XSS Detected
        SQLInjectionCheck --> SecurityInvalid: SQLi Detected
        CSRFCheck --> SecurityInvalid: CSRF Risk
        ClickjackCheck --> SecurityInvalid: Clickjack Risk

        SecurityValid --> [*]
        SecurityInvalid --> [*]
    }

    SecurityValidation --> HTMLValidation: Security Valid
    SecurityValidation --> ValidationFailed: Security Invalid

    state HTMLValidation {
        [*] --> ParseHTML
        ParseHTML --> CheckDoctype: Parse OK
        CheckDoctype --> CheckMeta: Doctype OK
        CheckMeta --> CheckSemantic: Meta OK
        CheckSemantic --> CheckAccessibility: Semantic OK
        CheckAccessibility --> HTMLValid: Accessibility OK

        ParseHTML --> HTMLInvalid: Parse Error
        CheckDoctype --> HTMLInvalid: Missing/Wrong
        CheckMeta --> HTMLInvalid: Meta Issues
        CheckSemantic --> HTMLInvalid: Semantic Issues
        CheckAccessibility --> HTMLInvalid: A11y Issues

        HTMLValid --> [*]
        HTMLInvalid --> [*]
    }

    HTMLValidation --> ValidationComplete: HTML Valid
    HTMLValidation --> ValidationFailed: HTML Invalid

    ValidationComplete --> [*]: All Checks Passed

    ValidationFailed --> ErrorLogging: Log Failure Details

    ErrorLogging --> RetryDecision: Assess Error

    state RetryDecision <<choice>>
    RetryDecision --> RetryGeneration: Fixable Error
    RetryDecision --> RejectContent: Unfixable Error

    RetryGeneration --> ValidationQueued: Retry

    RejectContent --> [*]: Validation Failed

    note right of SchemaValidation
        JSON Schema validation:
        - Structure conformance
        - Type checking
        - Required fields
        - Value constraints
    end note

    note right of ContentValidation
        Content sanitization:
        - XSS prevention
        - HTML injection
        - Link validation
        - Length limits
    end note

    note right of SecurityValidation
        Security scanning:
        - OWASP Top 10
        - Input validation
        - Output encoding
        - CSP compliance
    end note
Loading

Validation Stage Details

Validation Type Checks Performed Failure Action Retry Allowed
Schema Validation JSON structure, types, required fields, constraints Log error, reject data Yes (1 retry)
Content Validation HTML sanitization, link validation, length checks Log error, sanitize or reject Yes (auto-fix)
Security Validation XSS, SQLi, CSRF, clickjacking, CSP violations Log error, reject content No
HTML Validation Parse errors, doctype, meta tags, semantics, accessibility Log error, auto-fix or reject Yes (auto-fix)

🚨 Error State Handling

The system handles errors through structured error states with recovery paths.

stateDiagram-v2
    [*] --> OperationNormal: Normal Operation

    OperationNormal --> ErrorDetected: Exception/Failure

    ErrorDetected --> ErrorClassification: Classify Error

    state ErrorClassification <<choice>>
    ErrorClassification --> TransientError: Retryable
    ErrorClassification --> PersistentError: Non-Retryable
    ErrorClassification --> FatalError: Critical

    state TransientError {
        [*] --> NetworkError
        [*] --> TimeoutError
        [*] --> RateLimitError
        [*] --> ServiceUnavailable

        NetworkError --> RetryQueue: Log & Queue
        TimeoutError --> RetryQueue: Log & Queue
        RateLimitError --> BackoffQueue: Log & Wait
        ServiceUnavailable --> RetryQueue: Log & Queue

        RetryQueue --> [*]
        BackoffQueue --> [*]
    }

    TransientError --> RetryAttempt: Enter Retry

    state RetryAttempt {
        [*] --> WaitBackoff
        WaitBackoff --> IncrementCounter: Backoff Complete
        IncrementCounter --> CheckRetryLimit: Counter++

        state CheckRetryLimit <<choice>>
        CheckRetryLimit --> RetryOperation: Retry < Max
        CheckRetryLimit --> ExhaustedRetries: Retry >= Max

        RetryOperation --> [*]: Retry
        ExhaustedRetries --> [*]: Give Up
    }

    RetryAttempt --> OperationNormal: Retry Success
    RetryAttempt --> PersistentError: Max Retries

    state PersistentError {
        [*] --> ValidationError
        [*] --> ConfigurationError
        [*] --> DataQualityError
        [*] --> AuthenticationError

        ValidationError --> ErrorLogged: Log Details
        ConfigurationError --> ErrorLogged: Log Details
        DataQualityError --> ErrorLogged: Log Details
        AuthenticationError --> ErrorLogged: Log Details

        ErrorLogged --> [*]
    }

    PersistentError --> FallbackMode: Use Fallback

    state FallbackMode {
        [*] --> UsePlaceholder
        UsePlaceholder --> ContinueWorkflow: Placeholder Active
        ContinueWorkflow --> [*]
    }

    FallbackMode --> OperationDegraded: Continue with Limitations

    state FatalError {
        [*] --> SystemError
        [*] --> SecurityViolation
        [*] --> DataCorruption
        [*] --> ResourceExhaustion

        SystemError --> CriticalAlert: Alert Team
        SecurityViolation --> CriticalAlert: Alert Team
        DataCorruption --> CriticalAlert: Alert Team
        ResourceExhaustion --> CriticalAlert: Alert Team

        CriticalAlert --> [*]
    }

    FatalError --> WorkflowAborted: Terminate

    WorkflowAborted --> NotificationSent: Send Alerts

    NotificationSent --> [*]: End Workflow

    OperationDegraded --> OperationNormal: Recovery

    note right of TransientError
        Retry with exponential backoff:
        - 1st retry: 1s delay
        - 2nd retry: 2s delay
        - 3rd retry: 4s delay
        Max 3 retries
    end note

    note right of PersistentError
        Errors requiring intervention:
        - Invalid configuration
        - Bad input data
        - Authentication issues
        - Resource not found
    end note

    note right of FatalError
        Critical failures:
        - Security violations
        - Data corruption
        - Out of memory
        - Infinite loops
    end note
Loading

Error Classification Matrix

Error Type Severity Retry Strategy Fallback Alert
Network Error Transient 3 retries, exponential backoff Continue with cache No
Timeout Error Transient 3 retries, extended timeout Skip operation No
Rate Limit Error Transient Wait + retry (per X-RateLimit headers) Queue for later No
Service Unavailable Transient 3 retries, exponential backoff Use fallback service Warning
Validation Error Persistent 1 retry with fix Use last valid data Warning
Configuration Error Persistent No retry Use defaults Error
Data Quality Error Persistent No retry Skip corrupt data Warning
Authentication Error Persistent 1 retry Abort workflow Error
System Error Fatal No retry Abort Critical
Security Violation Fatal No retry Abort Critical
Data Corruption Fatal No retry Abort Critical
Resource Exhaustion Fatal No retry Abort Critical

📦 Deployment State Lifecycle

After content generation, the deployment process manages Git operations and GitHub Pages deployment.

stateDiagram-v2
    [*] --> PreDeployment: Content Validated

    PreDeployment --> GitStaging: Stage Changes

    state GitStaging {
        [*] --> GitAdd
        GitAdd --> GitStatus: Add Files
        GitStatus --> ChangesStaged: Verify
        ChangesStaged --> [*]

        GitAdd --> GitError: Add Failed
        GitStatus --> GitError: Status Check Failed
        GitError --> [*]
    }

    GitStaging --> GitCommit: Files Staged
    GitStaging --> DeploymentFailed: Staging Failed

    state GitCommit {
        [*] --> CreateCommit
        CreateCommit --> SignCommit: Commit Created
        SignCommit --> VerifyCommit: Signature Added
        VerifyCommit --> CommitComplete: Verify OK

        CreateCommit --> CommitError: Commit Failed
        SignCommit --> CommitError: Sign Failed
        VerifyCommit --> CommitError: Verify Failed

        CommitComplete --> [*]
        CommitError --> [*]
    }

    GitCommit --> GitPush: Commit Success
    GitCommit --> DeploymentFailed: Commit Failed

    state GitPush {
        [*] --> PushToRemote
        PushToRemote --> VerifyPush: Push Initiated
        VerifyPush --> PushSuccess: Remote Updated

        PushToRemote --> PushConflict: Conflict Detected
        PushConflict --> PullRebase: Pull Changes
        PullRebase --> PushToRemote: Retry Push

        PushToRemote --> PushError: Network Error
        PushError --> RetryPush: Retry
        RetryPush --> PushToRemote: Wait & Retry

        PushSuccess --> [*]
        PushError --> [*]
    }

    GitPush --> GitHubPagesQueue: Push Success
    GitPush --> DeploymentFailed: Push Failed

    state GitHubPagesQueue {
        [*] --> Queued
        Queued --> Building: Build Started
        Building --> Deploying: Build Success
        Deploying --> DeploySuccess: Deploy Complete

        Building --> BuildError: Build Failed
        Deploying --> DeployError: Deploy Failed

        BuildError --> [*]
        DeployError --> [*]
        DeploySuccess --> [*]
    }

    GitHubPagesQueue --> DeploymentComplete: Pages Live
    GitHubPagesQueue --> DeploymentFailed: Pages Failed

    DeploymentComplete --> VerifyDeployment: Verify

    state VerifyDeployment {
        [*] --> HealthCheck
        HealthCheck --> ValidateContent: HTTP 200
        ValidateContent --> CheckIndexes: Content OK
        CheckIndexes --> VerifySuccess: Indexes OK

        HealthCheck --> VerifyFailed: HTTP Error
        ValidateContent --> VerifyFailed: Content Mismatch
        CheckIndexes --> VerifyFailed: Missing Indexes

        VerifySuccess --> [*]
        VerifyFailed --> [*]
    }

    VerifyDeployment --> DeploymentMonitored: Verify Success
    VerifyDeployment --> DeploymentDegraded: Verify Failed

    DeploymentMonitored --> [*]: Deployment Complete

    DeploymentFailed --> ErrorNotification: Alert Team
    DeploymentDegraded --> WarningNotification: Alert Team

    ErrorNotification --> [*]: Workflow Failed
    WarningNotification --> DeploymentMonitored: Continue Monitoring

    note right of GitCommit
        Commit includes:
        - Generated articles
        - Updated indexes
        - Sitemap.xml
        Co-authored-by trailer
    end note

    note right of GitHubPagesQueue
        GitHub Pages automatically:
        - Builds Jekyll site
        - Deploys to CDN
        - Updates DNS
        ~90-180 seconds
    end note

    note right of VerifyDeployment
        Post-deployment checks:
        - HTTP status codes
        - Content integrity
        - Index availability
        - Sitemap accessibility
    end note
Loading

Deployment State Details

State Description Duration Rollback
PreDeployment Final checks before commit 5s Yes
GitStaging Adding files to Git index 10s Yes
GitCommit Creating signed commit 5s Yes
GitPush Pushing to GitHub remote 10-30s No*
GitHubPagesQueue GitHub Pages build queue 30-90s No
Building Jekyll build process 30-60s No
Deploying CDN deployment 30-60s No
DeploymentComplete Live on GitHub Pages Permanent No
VerifyDeployment Post-deploy validation 30s N/A
DeploymentMonitored Monitoring active Ongoing N/A
DeploymentFailed Critical failure N/A Rollback
DeploymentDegraded Partial failure Until fixed Manual

*Git push can be reverted with git revert, but GitHub Pages redeploys.

🔁 Pipeline-Stage State Machine

The 5-stage pipeline in src/generators/pipeline/ is the canonical execution spine invoked by every strategy in src/generators/strategies/. Each stage has explicit entry/exit states and retry semantics.

stateDiagram-v2
    [*] --> FetchStage: Strategy.run() invoked

    state FetchStage {
        [*] --> FetchingEP
        FetchingEP --> FetchingWB: EP OK
        FetchingEP --> FetchingEPRetry: Unavailable envelope
        FetchingEPRetry --> FetchingEP: Backoff (mcp-retry.ts)
        FetchingEPRetry --> FetchingWB: Max retries (degrade)
        FetchingWB --> FetchingIMF: WB OK or OR-gate allows
        FetchingWB --> FetchingIMF: WB Skip (optional)
        FetchingIMF --> FetchComplete: IMF OK
        FetchingIMF --> FetchComplete: IMF skip (WB satisfies OR-gate)
        FetchingIMF --> FetchFailed: Both WB+IMF failed
        FetchComplete --> [*]
        FetchFailed --> [*]
    }

    FetchStage --> TransformStage: Fetch complete
    FetchStage --> PipelineAborted: Fetch failed (economic OR-gate blocked)

    state TransformStage {
        [*] --> NormalizingEP
        NormalizingEP --> NormalizingEconomic: EP normalized
        NormalizingEconomic --> Unifying: Economic normalized
        Unifying --> TransformComplete: Schema unified
        TransformComplete --> [*]
    }

    TransformStage --> AnalysisStage: Unified data ready

    state AnalysisStage {
        [*] --> Pass1Writing
        Pass1Writing --> Pass1Complete: Pass 1 done (60% budget)
        Pass1Complete --> Pass2Improving: Read-back + improve
        Pass2Improving --> Pass2Complete: Pass 2 done (40% budget)
        Pass2Complete --> IntelligenceFiles: Emit analysis files
        IntelligenceFiles --> AnalysisComplete: stakeholder-map.md<br/>impact-matrix.md<br/>mcp-reliability-audit.md<br/>reference-analysis-quality.md
        AnalysisComplete --> [*]
        Pass1Writing --> AnalysisFailed: Time budget exhausted
        AnalysisFailed --> [*]
    }

    AnalysisStage --> GenerateStage: Analysis complete
    AnalysisStage --> PipelineAborted: Analysis failed

    state GenerateStage {
        [*] --> StrategyBuilder
        StrategyBuilder --> StakeholderSlots: buildDefaultStakeholderPerspectives
        StakeholderSlots --> ChartEmbedding: AI_MARKER sentinels
        ChartEmbedding --> RenderHTML: Chart.js embedded
        RenderHTML --> GenerateComplete: HTML rendered
        GenerateComplete --> [*]
    }

    GenerateStage --> OutputStage: HTML ready

    state OutputStage {
        [*] --> WritingFiles
        WritingFiles --> UpdatingIndexes: news/ updated
        UpdatingIndexes --> OutputComplete: Indexes + sitemap
        OutputComplete --> [*]
    }

    OutputStage --> ValidatorGate: Ready for gate
    ValidatorGate --> [*]: Pass → PR created
    ValidatorGate --> PipelineAborted: Fail
    PipelineAborted --> [*]: Abort workflow

    note right of FetchStage
        EP MCP 1.2.11 uniform
        unavailable envelope:
        { status:"unavailable",
          items:[] }
        WB-or-IMF OR-gate via
        articlePolicyHasEconomicContext
    end note

    note right of AnalysisStage
        AI-First quality gates:
        ≥80 words/SWOT item
        ≥150 words/stakeholder
        ≥60% prose ratio
        ≥1 Chart.js
        0 AI_ANALYSIS_REQUIRED
        60-min ≥45m; 120-min ≥90m
    end note
Loading

✅ Validator-Gate State Machine

node scripts/utils/validate-analysis-completeness.js --article-html=... runs as a pre-translation and pre-PR gate. Implemented via scanHtmlForFallbackLeaks + FALLBACK_TEMPLATE_PATTERNS.

stateDiagram-v2
    [*] --> Scanning: Invoked with --article-html

    Scanning --> AnalysisPresent: Analysis files exist
    Scanning --> MissingManifest: Missing analysis files

    AnalysisPresent --> ManifestValid: Reference thresholds met
    AnalysisPresent --> InsufficientReferences: Below threshold

    ManifestValid --> ArticleClean: No fallback template patterns
    ManifestValid --> FallbackLeak: AI_ANALYSIS_REQUIRED or AI_MARKER leak

    ArticleClean --> EconomicContextOK: articlePolicyHasEconomicContext passes
    ArticleClean --> MissingEconomicContext: No WB and no IMF

    EconomicContextOK --> Pass: All gates OK
    Pass --> [*]: PR creation allowed

    MissingManifest --> Fail
    InsufficientReferences --> Fail
    FallbackLeak --> Fail
    MissingEconomicContext --> Fail
    Fail --> [*]: Abort PR

    note right of ManifestValid
        intelligence/mcp-reliability-audit.md
          ≥200 words (breaking ≥385)
        intelligence/reference-analysis-quality.md
          ≥140 words (breaking ≥190)
        Configured in
        analysis/methodologies/
        reference-quality-thresholds.json
    end note

    note right of ArticleClean
        scanHtmlForFallbackLeaks
        checks rendered HTML against
        FALLBACK_TEMPLATE_PATTERNS
    end note
Loading

Validator Failure Categories

Category Trigger Remediation
MissingManifest Analysis stage did not emit required intelligence files Re-run analysis stage with longer time budget
InsufficientReferences Word-count thresholds not met Extend AI reasoning; verify Pass-2 improvement actually ran
FallbackLeak AI_ANALYSIS_REQUIRED / AI_MARKER sentinels present in rendered HTML Agent author must fill slots directly; re-run generate stage
MissingEconomicContext Both WB and IMF unavailable Wait for one economic source to recover, or relax default gate to articlePolicyHasEconomicContext

🌍 Translation State Machine (news-translate)

The news-translate agentic workflow fans out one EN source article to 13 non-EN languages. A pre-gate scan validates analysis completeness before fan-out to prevent replicating broken EN content across languages.

stateDiagram-v2
    [*] --> PreGate: news-translate triggered

    state PreGate {
        [*] --> ScanAllEnglishSources
        ScanAllEnglishSources --> PreGatePass: All pass validator
        ScanAllEnglishSources --> PreGateFail: Any EN source fails
        PreGatePass --> [*]
        PreGateFail --> [*]
    }

    PreGate --> Fanout: Pre-gate pass
    PreGate --> [*]: Pre-gate fail (abort)

    state Fanout {
        [*] --> Queued13
        Queued13 --> InProgress: Per-language job starts
        InProgress --> Validated: axe-core + htmlhint pass
        Validated --> Committed: Language HTML committed
        Committed --> Reconciled: news-translate-reconciler cleanup
        Reconciled --> [*]

        InProgress --> LanguageFailed: Translation / validation failed
        LanguageFailed --> Requeue: Within max-patch-size 10240 KB
        Requeue --> InProgress: Retry
        LanguageFailed --> SkipLanguage: Max retries
        SkipLanguage --> [*]: Partial fan-out
    }

    Fanout --> PRCreated: All languages processed
    PRCreated --> [*]: safe-outputs create-pull-request

    note right of PreGate
        validate-analysis-completeness.js
        runs against every EN HTML
        source before fan-out —
        prevents fan-out of broken
        analysis across 13 languages
    end note

    note right of Fanout
        Languages: sv, da, no, fi, de,
        fr, es, nl, ar, he, ja, ko, zh
        max-patch-size: 10240 KB
        (vs default 1024 KB)
    end note
Loading

🎨 Color Legend & Styling

State diagrams use consistent colors to indicate state categories:

stateDiagram-v2
    [*] --> Normal: Normal States
    [*] --> Transient: Transient States
    [*] --> Error: Error States
    [*] --> Success: Success States
    [*] --> Critical: Critical States

    state Normal {
        [*] --> Processing
        [*] --> Waiting
        [*] --> Active
    }

    state Transient {
        [*] --> Connecting
        [*] --> Retrying
        [*] --> Loading
    }

    state Error {
        [*] --> Failed
        [*] --> Rejected
        [*] --> Invalid
    }

    state Success {
        [*] --> Complete
        [*] --> Validated
        [*] --> Published
    }

    state Critical {
        [*] --> Fatal
        [*] --> Aborted
        [*] --> SecurityViolation
    }

    note right of Normal
        Light blue/gray:
        Regular processing states
    end note

    note right of Transient
        Yellow/amber:
        Temporary states during
        transitions
    end note

    note right of Error
        Red/pink:
        Error states requiring
        attention
    end note

    note right of Success
        Green:
        Successfully completed
        states
    end note

    note right of Critical
        Dark red:
        Critical failures requiring
        immediate intervention
    end note
Loading
Color State Type Example States
🔵 Light Blue Normal Processing Active, Generating, Processing
🟡 Yellow Transient Connecting, Retrying, Loading
🟢 Green Success Complete, Validated, Published, Deployed
🔴 Red Error Failed, Rejected, Invalid
⚫ Dark Red Critical Fatal, Aborted, SecurityViolation
⚪ White Initial/Final [*] start and end states

📊 State Metrics & Monitoring

Key Performance Indicators

Metric Target Measurement Alert Threshold
Time in Idle >95% Percentage of time waiting <90% (overloaded)
Initialization Success Rate >99% Successful init / total attempts <95%
MCP Connection Success Rate >95% Connected / connection attempts <90%
Article Generation Success Rate >98% Published / attempted <95%
Validation Pass Rate >99% Passed / total validations <98%
Deployment Success Rate >99% Successful deploys / attempts <98%
Error Recovery Rate >90% Recovered / total errors <80%
Fallback Activation Rate <5% Fallback / total attempts >10%

State Duration Targets

State Target Duration Warning Threshold Error Threshold
Initialization <30s >45s >60s
MCP Connection <10s >20s >30s
Data Fetching <30s >60s >90s
Article Generation <120s >180s >300s
Validation <30s >45s >60s
Testing <60s >90s >120s
Git Operations <30s >45s >60s
GitHub Pages Deploy <90s >150s >300s

Monitoring Commands

# Check current workflow state
gh workflow view news-generation --repo Hack23/euparliamentmonitor

# View recent workflow runs
gh run list --workflow=news-generation.yml --limit 20

# Monitor specific run state
gh run watch <run-id>

# Check GitHub Pages deployment status
gh api repos/Hack23/euparliamentmonitor/pages/builds/latest

# View state transition logs
gh run view <run-id> --log

🔐 Security State Considerations

State-Based Security Controls

  1. Immutable States: Once ArticlePublished, content cannot be modified (only reverted)
  2. Validation Gates: Cannot transition to Publishing without passing Validating
  3. Authentication States: MCP connection requires successful authentication
  4. Rate Limiting: Retry states implement exponential backoff to prevent DoS
  5. Error Isolation: Error states log details but don't expose sensitive information
  6. Audit Trail: All state transitions logged with timestamps and context

Compliance Requirements

Per Hack23 ISMS State Management Policy:

  • ISO 27001 A.8.2: All state transitions must be logged and auditable
  • ISO 27001 A.12.4: States must prevent unauthorized data modification
  • ISO 27001 A.14.2: State validation ensures data integrity
  • NIS2 Article 21: Error states must trigger incident response procedures

🔄 Related Documentation

Process Documents

Data Documents

Strategic Documents

  • MINDMAP.md: Conceptual system relationships
  • SWOT.md: Strategic analysis and opportunities

📅 Document Revision History

Version Date Author Changes
1.2 2026-04-20 CEO Added Pipeline-Stage, Validator-Gate, and Translation state machines for v0.8.40 (5-stage pipeline, validator gate with fallback-leak scan, news-translate fan-out across 13 languages with 10240 KB max-patch-size); refreshed article-types note to 7 types; updated review cadence
1.1 2026-02-24 CEO Updated review date and verified current state accuracy
1.0 2025-02-17 CEO Initial state diagram documentation with comprehensive state machines

📝 Footer

Document Classification: Public
ISMS Compliance: ISO 27001:2022, NIST CSF 2.0, CIS Controls v8.1, GDPR, NIS2, EU CRA aligned
Technology Stack: Node.js 25, TypeScript 6.0.3, gh-aw v0.69.0, AWS S3 + CloudFront, GitHub Pages (fallback), EP MCP 1.2.11, WB MCP 1.0.1, IMF REST SDMX 3.0
Architecture Pattern: Static Site Generator with Agentic AI-First Authoring and Zero Runtime Dependencies
Review Status: Active, next review 2026-07-20

🔄 State Diagrams — Behavioral Model for EU Parliament Monitor
Part of ISMS-compliant Architecture Documentation Suite

🏛️ GitHub Repository • 🛡️ ISMS Framework • 🌐 Hack23