📈 Create STATEDIAGRAM.md - State Transitions & Lifecycles

[pethers]

📋 Issue Type

Documentation / Architecture

🎯 Objective

Create comprehensive STATEDIAGRAM.md documenting state transitions, lifecycles, and state management for riksdagsmonitor's workflows, articles, and dashboards.

📊 Current State

• ❌ STATEDIAGRAM.md does not exist
• ⚠️ Article lifecycle states undocumented
• ⚠️ Workflow state transitions implicit
• ⚠️ Dashboard states not formally defined
• ⚠️ PR review states scattered

Existing Related Docs:

• ✅ ARCHITECTURE.md (system architecture)
• ✅ WORKFLOWS.md (GitHub Actions)
• ✅ THREAT_MODEL.md (security states)

🚀 Desired State

Comprehensive STATEDIAGRAM.md including:

1. News Article Lifecycle States

DRAFT → TRANSLATION → VALIDATION → REVIEW → APPROVED → PUBLISHED
  ↓        ↓            ↓            ↓          ↓           ↓
ERROR ← TRANSLATION_FAILED ← VALIDATION_FAILED ← REJECTED ← ROLLBACK

States:

• DRAFT - Article generated by Copilot agent, Swedish content only
• TRANSLATION - Multi-language translation in progress (12 additional languages)
• VALIDATION - scripts/validate-news-translations.js checking data-translate markers
• REVIEW - Human review in pull request
• APPROVED - PR approved, awaiting merge
• PUBLISHED - Merged to main, deployed to production
• ERROR - Failure state requiring intervention

2. Agentic Workflow States

GitHub Actions Workflow:

QUEUED → RUNNING → GENERATING → TRANSLATING → VALIDATING → 
SUCCESS/FAILURE → PR_CREATED → PR_REVIEW → MERGED/CLOSED

States:

• QUEUED - Workflow scheduled, awaiting runner
• RUNNING - Copilot agent active
• GENERATING - Article content generation from riksdag-regering-mcp
• TRANSLATING - Multi-language translation (14 languages)
• VALIDATING - Playwright validation, translation checks
• SUCCESS - All checks passed
• FAILURE - Workflow failed (hallucination, translation error, validation failure)
• PR_CREATED - Pull request opened
• PR_REVIEW - Human review in progress
• MERGED - Changes deployed
• CLOSED - PR rejected or cancelled

3. Dashboard Data States

LocalStorage Caching:

EMPTY → FETCHING → CACHED → STALE → REFRESHING → CACHED
  ↓        ↓          ↓        ↓          ↓           ↓
ERROR ← FETCH_FAILED ← ─── ← ─── ← REFRESH_FAILED ← ───

States:

• EMPTY - No cached data, initial load
• FETCHING - Requesting data from GitHub CDN
• CACHED - Valid cached data (< freshness threshold)
• STALE - Cached data expired (> freshness threshold)
• REFRESHING - Background refresh in progress
• ERROR - Fetch/refresh failed, fallback to stale cache

Freshness Thresholds:

• Production stats: 24 hours
• Seasonal patterns: 7 days
• Politician data: 24 hours
• Party performance: 7 days

4. Pull Request Review States

OPEN → CI_RUNNING → CI_PASSED → REVIEW_REQUESTED → 
APPROVED → MERGE_READY → MERGED → DEPLOYED
  ↓        ↓            ↓            ↓              ↓
DRAFT ← CI_FAILED ← CHANGES_REQUESTED ← REVIEW_DISMISSED ← CLOSED

States:

• OPEN - PR created, awaiting CI
• DRAFT - Work-in-progress, not ready for review
• CI_RUNNING - Quality checks executing
• CI_PASSED - All checks passed
• CI_FAILED - Quality gate failed (HTML validation, link check, tests)
• REVIEW_REQUESTED - Assigned to reviewer
• CHANGES_REQUESTED - Feedback provided, changes needed
• APPROVED - Approved by reviewer
• REVIEW_DISMISSED - Previous approval dismissed
• MERGE_READY - All requirements met
• MERGED - Changes merged to main
• CLOSED - PR closed without merge
• DEPLOYED - Changes live in production

5. CI/CD Pipeline States

Deployment Pipeline:

COMMIT → BUILD → TEST → SCAN → DEPLOY_STAGING → 
HEALTH_CHECK → DEPLOY_PRODUCTION → MONITOR
  ↓        ↓       ↓       ↓            ↓              ↓
ROLLBACK ← ─── ← FAILED ← VULNERABLE ← UNHEALTHY ← ERRORS_DETECTED

States:

• COMMIT - Code pushed to repository
• BUILD - Vite build executing
• TEST - Unit tests (Vitest) and E2E tests (Cypress)
• SCAN - Security scanning (CodeQL, Dependabot, Secret Scanning)
• FAILED - Build/test/scan failure
• VULNERABLE - Security vulnerability detected
• DEPLOY_STAGING - Deploying to preview environment
• HEALTH_CHECK - Smoke tests on staging
• UNHEALTHY - Health check failed
• DEPLOY_PRODUCTION - Deploying to GitHub Pages + AWS CloudFront
• MONITOR - Production monitoring active
• ERRORS_DETECTED - Production errors detected
• ROLLBACK - Reverting to previous version

6. Translation Validation States

UNTRANSLATED → MARKED → TRANSLATING → TRANSLATED → VALIDATED → PUBLISHED
      ↓          ↓           ↓            ↓            ↓            ↓
    SKIP ← ──────── ← FAILED ← RETRYING ← INVALID ← ──────── ← ROLLBACK

States:

• UNTRANSLATED - Swedish API content not yet translated
• MARKED - data-translate="true" lang="sv" markers added
• TRANSLATING - Agentic translation in progress
• TRANSLATED - All languages completed
• VALIDATED - scripts/validate-news-translations.js passed (exit 0)
• INVALID - Validation failed (remaining markers detected, exit 1)
• FAILED - Translation error (hallucination, context loss)
• RETRYING - Retry translation attempt
• PUBLISHED - Clean translated content live
• ROLLBACK - Revert to previous version

🤖 AI Policy Compliance Context

Per Hack23 AI Policy:

• Agentic Workflow States must include AI-specific states (GENERATING, HALLUCINATION_DETECTED)
• Error States must capture AI failures (prompt injection, data poisoning)
• Human Oversight States required for Limited Risk AI systems (REVIEW, APPROVED)
• Audit States for compliance (LOGGED, MONITORED)

🔧 Implementation Approach

1. Mermaid State Diagrams

Create detailed Mermaid state diagrams:

stateDiagram-v2
    [*] --> Draft
    Draft --> Translation
    Translation --> Validation
    Translation --> TranslationFailed
    Validation --> Review
    Validation --> ValidationFailed
    Review --> Approved
    Review --> Rejected
    Approved --> Published
    Published --> [*]
    TranslationFailed --> Draft
    ValidationFailed --> Draft
    Rejected --> Draft

Loading

2. State Transition Tables

For each state diagram:

• From State | Event | To State | Conditions | Actions
• Example: DRAFT | translate_complete | TRANSLATION | all_languages_done | validate()

3. State Invariants

Document state invariants:

• PUBLISHED → Cannot transition back to DRAFT (immutable)
• CI_FAILED → Cannot transition to DEPLOY (must fix first)
• UNTRANSLATED → Cannot transition to PUBLISHED (blocking)

4. Error State Handling

For each error state:

• Detection - How error is detected
• Recovery - Automatic or manual recovery
• Retry Logic - Exponential backoff, max attempts
• Notification - GitHub issue, Slack alert, email

5. State Metrics

• Time in State - Average duration
• State Transitions - Frequency matrix
• Error Rates - Failed transitions percentage
• Bottlenecks - States with long durations

📚 References

Repository:

• Create: https://github.com/Hack23/riksdagsmonitor/blob/main/STATEDIAGRAM.md
• Architecture: https://github.com/Hack23/riksdagsmonitor/blob/main/ARCHITECTURE.md
• Workflows: https://github.com/Hack23/riksdagsmonitor/blob/main/WORKFLOWS.md

CIA References:

• CIA State Diagram: https://github.com/Hack23/cia/blob/master/STATEDIAGRAM.md

ISMS Policies:

• Secure Development Policy: https://github.com/Hack23/ISMS-PUBLIC/blob/main/Secure_Development_Policy.md
• Change Management: https://github.com/Hack23/ISMS-PUBLIC/blob/main/Change_Management.md
• AI Policy: https://github.com/Hack23/ISMS-PUBLIC/blob/main/AI_Policy.md

✅ Acceptance Criteria

• STATEDIAGRAM.md created with comprehensive state diagrams
• News article lifecycle states (DRAFT → PUBLISHED)
• Agentic workflow states (QUEUED → MERGED)
• Dashboard data states (EMPTY → CACHED)
• Pull request review states (OPEN → MERGED)
• CI/CD pipeline states (COMMIT → DEPLOYED)
• Translation validation states (UNTRANSLATED → VALIDATED)
• Mermaid state diagrams (6+ diagrams)
• State transition tables with conditions and actions
• State invariants documented
• Error state handling and recovery procedures
• State metrics and monitoring
• AI-specific states per Hack23 AI Policy
• Document control metadata (version, owner, last updated)
• Integration with ARCHITECTURE.md and WORKFLOWS.md
• Reviewed by documentation-architect agent

🤖 Recommended Agent

documentation-architect - Specialized in Mermaid state diagrams, lifecycle documentation, and workflow state management

🏷️ Labels

type:documentation, priority:high, component:architecture, component:workflow, component:ai-workflows, isms, agent:documentation-architect