🏛️ EU Parliament Monitor

European Parliament Intelligence Platform
Monitor political activity with systematic transparency

European Parliament Intelligence Platform — an automated multi-language news platform that monitors EU Parliament activities with 14-language support, covering plenary sessions, committee reports, propositions, and breaking news. 📂 Repository • ✨ Features • 📚 Documentation

🎯 Status Badges

Workflow Status

Documentation & Reports

📚 Documentation Hub

📖 Quick Links:

• 📘 Architecture Documentation - Complete security architecture with C4 diagrams
• 📗 Security Flows - Process flows with security controls
• 📙 Data Model - Data structures and API integration
• 📕 Release Process - How to create releases
• 📔 API Documentation - TypeDoc-generated API reference
• 📓 Test Coverage - Interactive coverage report

🔒 ISMS Compliance:

• 🛡️ Hack23 ISMS Framework - Information Security Management System
• 🔐 Secure Development Policy - Development standards
• 📋 Classification Framework - CIA triad classification

Current Status

MCP Server Integration: The project is designed to use the European-Parliament-MCP-Server for accessing real EU Parliament data.

• MCP Server Status: The MCP server is currently in development (skeleton implementation)
• Fallback Mode: News generation works with placeholder content when MCP server is unavailable
• Environment Variable: Set USE_EP_MCP=false to disable MCP client connection attempts

When MCP Server is Ready

Once the European-Parliament-MCP-Server is fully implemented, the system will automatically:

1. Connect to the MCP server for real-time EU Parliament data
2. Fetch plenary sessions, committee meetings, and documents
3. Generate articles with actual parliamentary information
4. Provide proper translation or content generation in each language

Current Limitations

Note: The current implementation generates placeholder content in English for all languages when MCP server is unavailable. To enable full functionality:

1. Complete the MCP Server: The European-Parliament-MCP-Server needs implementation of:

   • get_plenary_sessions tool
   • search_documents tool
   • get_parliamentary_questions tool
   • get_committee_info tool

2. Install MCP Server: Once ready, install the MCP server:

   npm install -g european-parliament-mcp-server
   # or clone and build locally
   Copy

3. Enable MCP Client: The news generator will automatically connect when the server is available

EU Parliament Monitor is an automated news generation platform that monitors European Parliament activities and generates multi-language news articles covering:

• Week Ahead: Preview of upcoming parliamentary events and committee meetings
• Committee Reports: Analysis of committee activities and decisions
• Propositions: Government and parliamentary legislative proposals
• Motions: Parliamentary motions and resolutions
• Breaking News: Rapid-response coverage of significant developments

Features

• 📰 Automated News Generation: Generate news articles about EU Parliament activities
• 🌍 Multi-Language Support: 14 languages including English, German, French, Spanish, Italian, and more
• 📅 Week Ahead Coverage: Preview upcoming parliamentary events
• 🤖 GitHub Actions Integration: Automated daily news generation
• 📊 SEO Optimized: Proper metadata, structured data, and sitemap generation
• ✅ Code Quality: ESLint, Prettier, and automated quality gates

🔒 Security Architecture

EU Parliament Monitor implements security-by-design with comprehensive security controls and ISMS compliance.

Security Documentation

• 📋 Security Architecture - Complete security implementation overview with C4 diagrams, threat model, and compliance mapping
• 🚀 Future Security Architecture - Security enhancement roadmap (2026-2027)
• 📊 Data Model - Data structures and European Parliament API integration
• 📈 Security Flowcharts - Detailed process flows with security controls

Security Posture

Classification (per ISMS Classification Framework):

• Confidentiality: Public (Level 1) - European Parliament open data
• Integrity: Medium (Level 2) - News accuracy critical for democratic transparency
• Availability: Medium (Level 2) - Daily updates expected, 24h RTO acceptable

Key Security Controls:

• ✅ Minimal Attack Surface: Static site, no databases, no server-side execution
• ✅ Automated Security: CodeQL SAST, Dependabot SCA, npm audit
• ✅ Supply Chain Security: SHA-pinned GitHub Actions, SBOM generation
• ✅ Input Validation: Multi-layer XSS prevention, HTML sanitization
• ✅ Infrastructure Security: GitHub-hosted ephemeral runners, HTTPS enforcement
• ✅ Compliance: ISO 27001, GDPR, NIS2, EU CRA aligned

Security Metrics:

• Zero known vulnerabilities (npm audit clean)
• 82%+ code coverage with security tests
• 100% dependency scanning coverage
• 0 CodeQL critical/high findings

ISMS Alignment

This project follows Hack23 ISMS Secure Development Policy:

• ✅ Security architecture documentation (C4 models with Mermaid)
• ✅ Threat modeling (STRIDE analysis)
• ✅ Security testing (SAST, SCA, unit tests)
• ✅ Compliance mapping (ISO 27001, GDPR, NIS2)

🤝 Community & Governance

EU Parliament Monitor is an open source project with transparent governance and community standards.

Open Source Standards

• Contributing Guide - Development workflow, code standards, and contribution guidelines
• Code of Conduct - Community standards based on Contributor Covenant 2.1
• Security Policy - Vulnerability disclosure and security practices
• Authors & Contributors - Recognition of project contributors
• License - Apache License 2.0 full text

Community Channels

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: Questions and community discussion
• Security: security@hack23.com for vulnerability reports
• Conduct: conduct@hack23.com for Code of Conduct issues

Governance Compliance

This project adheres to:

• ✅ OpenSSF Best Practices: Following CII Best Practices criteria
• ✅ ISMS Compliance: Aligned with Hack23 ISMS policies
• ✅ Transparent Development: Public repository, open discussions
• ✅ Security First: Comprehensive security disclosure policy

Code Quality & Testing

EU Parliament Monitor maintains high code quality standards with comprehensive testing:

Code Quality

• ESLint: Comprehensive linting with security, complexity, and documentation checks
• Prettier: Consistent code formatting across all JavaScript files
• Pre-commit Hooks: Automatic linting and formatting before every commit
• CI/CD Quality Gates: Automated checks on every pull request
• TypeDoc/JSDoc: Complete documentation for all functions

Code Standards: See docs/CODE_STANDARDS.md for detailed coding guidelines.

Testing Infrastructure

Comprehensive test suite with Vitest and Playwright covering all functionality:

Unit & Integration Tests (Vitest)

• Unit Tests: Article generation, MCP client, index/sitemap generation
• Integration Tests: Full workflows, MCP integration, multi-language support
• Coverage: ≥80% line coverage, ≥75% branch coverage
• Test Count: 169+ tests covering critical paths

# Run unit & integration tests
npm test

# Run with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

# Run with UI (browser interface)
npm run test:ui
Copy

End-to-End Tests (Playwright)

• E2E Tests: Complete user experience validation
• Cross-Browser: Chromium, Firefox, WebKit
• Mobile Support: Mobile Chrome, Mobile Safari
• Accessibility: WCAG 2.1 AA compliance with axe-core
• Responsive Design: Multiple viewport sizes
• Test Count: 60+ E2E tests covering user journeys

# Run E2E tests
npm run test:e2e

# Run with UI (interactive)
npm run test:e2e:ui

# Run in headed mode (see browser)
npm run test:e2e:headed

# View test report
npm run test:e2e:report
Copy

Testing Documentation:

• test/README.md - Unit & integration tests
• e2e/README.md - E2E testing guide

Custom Agents

EU Parliament Monitor includes 8 specialized GitHub Copilot custom agents to streamline development:

• 🤖 product-task-agent - Product specialist for issue creation and coordination
• 📰 news-journalist - The Economist-style European Parliament reporting
• 🎨 frontend-specialist - HTML5/CSS3/WCAG 2.1 AA UI/UX expert
• 🔄 data-pipeline-specialist - European Parliament MCP integration expert
• ⚙️ devops-engineer - CI/CD and GitHub Actions automation
• 🔒 security-architect - ISMS, GDPR, NIS2 compliance expert
• 📚 documentation-architect - C4 models and architecture docs
• ✅ quality-engineer - Testing, validation, and accessibility

Usage Example:

# Use product-task-agent to analyze repository and create improvement issues
@product-task-agent analyze the multi-language support and create issues for any gaps

# Use news-journalist to generate content
@news-journalist create a week-ahead article for the upcoming plenary session

# Use frontend-specialist for UI improvements
@frontend-specialist make the language switcher fully keyboard accessible
Copy

Learn More: See Custom Agents Documentation for detailed agent capabilities, usage patterns, and examples.

Languages Supported

• EU Core: English (en), German (de), French (fr), Spanish (es), Italian (it), Dutch (nl)
• Nordic: Swedish (sv), Danish (da), Finnish (fi)
• Eastern Europe: Polish (pl), Romanian (ro), Hungarian (hu)
• Other: Portuguese (pt), Greek (el)

Requirements

• Node.js: Version 24 or higher
• npm: Version 10 or higher (comes with Node.js 24)
• Git: For cloning the repository

You can verify your Node.js version with:

node --version  # Should be v24.x.x or higher
npm --version   # Should be 10.x.x or higher
Copy

Installation

# Clone the repository
git clone https://github.com/Hack23/euparliamentmonitor.git
cd euparliamentmonitor

# Install dependencies
npm install
Copy

Optional: European Parliament MCP Server

For real EU Parliament data integration, install the MCP server:

# Clone the MCP server repository
git clone https://github.com/Hack23/European-Parliament-MCP-Server.git
cd European-Parliament-MCP-Server

# Install dependencies and build
npm install
npm run build

# The server will be available at dist/index.js
# You can install it globally or reference the path
Copy

Configure the MCP server path in environment variables:

export EP_MCP_SERVER_PATH="/path/to/European-Parliament-MCP-Server/dist/index.js"
Copy

Note: The MCP server is currently in development. News generation works without it using placeholder content.

Usage

Generate News Articles

# Generate week ahead article in English
npm run generate-news -- --types=week-ahead --languages=en

# Generate multiple article types in multiple languages
npm run generate-news -- --types=week-ahead,committee-reports --languages=en,de,fr

# Generate in all EU core languages
npm run generate-news -- --types=week-ahead --languages=eu-core

# Generate in all supported languages
npm run generate-news -- --types=week-ahead --languages=all
Copy

Generate Indexes and Sitemap

# Generate language-specific index pages
npm run generate-news-indexes

# Generate sitemap.xml
npm run generate-sitemap
Copy

Local Development

# Serve the site locally
npm run serve

# Open http://localhost:8080 in your browser
Copy

Project Structure

euparliamentmonitor/
├── .github/
│   ├── agents/                      # Custom GitHub Copilot agents
│   ├── workflows/                   # CI/CD workflow configurations
│   └── release-drafter.yml          # Release notes configuration
├── src/                             # TypeScript source (compiles to scripts/)
│   ├── constants/                   # Language data, configuration
│   ├── generators/                  # News, index, sitemap generators
│   ├── mcp/                         # European Parliament MCP client
│   ├── templates/                   # HTML article templates
│   ├── types/                       # Shared TypeScript interfaces
│   └── utils/                       # File utilities, metadata
├── scripts/                         # Compiled JavaScript output
│   ├── constants/                   # Compiled constants
│   ├── generators/                  # Compiled generators
│   ├── mcp/                         # Compiled MCP client
│   ├── templates/                   # Compiled templates
│   ├── types/                       # Compiled type definitions
│   └── utils/                       # Compiled utilities
├── news/                            # Generated news articles
│   └── metadata/                    # Generation metadata
├── test/                            # Vitest unit & integration tests
├── e2e/                             # Playwright E2E tests
├── docs/                            # Generated documentation
├── styles.css                       # Article styling
├── index-{lang}.html                # Language-specific index pages
├── typedoc.json                     # TypeDoc configuration
├── tsconfig.json                    # TypeScript configuration
├── sitemap.xml                      # SEO sitemap
└── package.json                     # Project dependencies
Copy

CI/CD & Automation

GitHub Actions Workflows

The repository includes comprehensive GitHub Actions workflows for automation and quality assurance:

📰 News Generation

• Schedule: Runs daily at 06:00 UTC
• Manual Trigger: Can be triggered manually with custom parameters
• Automatic Commit: Commits and pushes generated articles automatically
• Workflow: .github/workflows/news-generation.yml

Workflow Inputs:

• article_types: Comma-separated list of article types (default: week-ahead)
• languages: Languages to generate (en, eu-core, all, or custom list)
• force_generation: Force generation even if recent articles exist

🏷️ PR Labeling

• Automatic: Labels PRs based on file changes
• Configuration: .github/labeler.yml
• Workflow: .github/workflows/labeler.yml
• Setup: Run .github/workflows/setup-labels.yml once to create all labels

📦 Release Management

• Automated Release Notes: Via Release Drafter
• Semantic Versioning: Based on PR labels
• SBOM & Attestations: Security compliance with artifact attestations
• Workflow: .github/workflows/release.yml
• Configuration: .github/release-drafter.yml

🔒 Security Scanning

• CodeQL: Automated security analysis on push, PR, and weekly schedule
• OpenSSF Scorecard: Supply chain security assessment (weekly, on branch protection changes)
• Dependabot: Weekly dependency updates for npm and GitHub Actions
• Dependency Review: Vulnerability scanning on pull requests
• Vulnerability Scanning: Automated npm audit in PR validation
• Workflows: .github/workflows/codeql.yml, .github/workflows/scorecards.yml, .github/dependabot.yml, .github/workflows/dependency-review.yml

🏆 Compliance & Quality

• REUSE Compliance: License header verification (FSFE REUSE specification)
• SonarCloud Analysis: Code quality, security vulnerabilities, and technical debt tracking
• SLSA Provenance: Level 3 build attestations with SBOM generation on releases
• Workflows: .github/workflows/reuse.yml, .github/workflows/sonarcloud.yml, .github/workflows/slsa-provenance.yml

✅ Test & Validation

• HTML Validation: Automated htmlhint checks
• Functional Tests: News generation, index, and sitemap validation
• Security Checks: npm audit for vulnerabilities
• Workflow: .github/workflows/test-and-report.yml

📊 Evidence: See Workflow Status Badges at top of README.

Workflow Status Badges

Core Workflows:

Security Workflows:

Compliance Workflows:

Manual Release Process

To create a new release:

1. Go to Actions → Release workflow
2. Click Run workflow
3. Enter version (e.g., v1.0.0)
4. Select if pre-release
5. The workflow will:
   • Run validation and tests (169 unit tests, E2E tests)
   • Generate API documentation (TypeDoc)
   • Generate test coverage reports (Vitest HTML)
   • Generate E2E test reports (Playwright)
   • Create documentation index
   • Commit documentation to main branch
   • Generate SBOM and attestations (SLSA Level 3)
   • Create GitHub release with artifacts
   • Update release notes automatically

🔒 ISMS Evidence:

• Release Workflow - Complete automation
• SLSA Attestations - Build provenance
• Release Process Guide - Step-by-step documentation

Documentation as Code

Every release automatically generates comprehensive documentation:

Documentation	Description	Link
API Documentation	TypeDoc-generated API reference from TypeScript source	View Docs
Test Coverage	Interactive Vitest coverage reports (82%+)	View Coverage
E2E Test Reports	Playwright test results with screenshots	View Report
Documentation Index	Beautiful hub linking all reports	View Index

📋 How It Works:

1. Release workflow runs all tests
2. Generates API docs with TypeDoc
3. Copies coverage reports to docs/
4. Creates documentation index page
5. Commits everything to main branch
6. Documentation is version-controlled and traceable

🎯 Run Locally:

npm run docs:generate  # Generate all documentation
npm run docs:api       # Generate API docs only
npm run docs:index     # Generate index page
Copy

🔒 ISMS Compliance:

• Documentation-as-code follows Hack23 ISMS Secure Development Policy §3.2
• All releases include complete documentation evidence
• Documentation committed to repository for full auditability

Setting Up Labels

First-time setup requires running the label creation workflow:

1. Go to Actions → Setup Repository Labels
2. Click Run workflow
3. Wait for completion
4. Labels will be automatically applied to future PRs

Configuration

Language Presets

• en - English only
• eu-core - English, German, French, Spanish, Italian, Dutch
• nordic - English, Swedish, Danish, Finnish
• all - All 14 supported languages

Article Types

• week-ahead - Preview of upcoming parliamentary events
• committee-reports - Committee activity analysis (coming soon)
• propositions - Legislative proposals analysis (coming soon)
• motions - Parliamentary motions analysis (coming soon)
• breaking - Breaking news coverage (coming soon)

Contributing

We welcome contributions from developers, journalists, translators, and security researchers!

How to Contribute

Please read our comprehensive Contributing Guide for:

• Development workflow and setup instructions
• Code quality requirements and testing standards
• Pull request process and review guidelines
• Security best practices and ISMS compliance
• Multi-language contribution guidelines

Code of Conduct

This project adheres to the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to conduct@hack23.com.

Security

If you discover a security vulnerability, please follow our Security Policy for responsible disclosure. Do not report security issues through public GitHub issues.

Contributors

See AUTHORS.md for a list of contributors who have helped make this project possible. Contributions are welcome! Please see CONTRIBUTING.md for detailed guidelines on:

• Code quality requirements (ESLint, Prettier, JSDoc)
• Testing requirements (80% line coverage, 75% branch coverage)
• Security requirements (input validation, XSS prevention, dependency scanning)
• Commit message format (conventional commits)
• Pull request process

Security-Critical Contributions: All security-related changes must align with SECURITY_ARCHITECTURE.md and Hack23 ISMS Secure Development Policy.

Security Policy

For security vulnerability reporting and disclosure process, please see SECURITY.md.

Responsible Disclosure:

• Report vulnerabilities privately via GitHub Security Advisories
• 48-hour acknowledgment, 7-day validation, 30-day remediation for critical issues
• Public recognition for security researchers (unless anonymity requested)

Badge Maintenance

Maintaining Security Badge Status

EU Parliament Monitor maintains security excellence through continuous compliance with OpenSSF best practices:

OpenSSF Scorecard (Target: ≥7.0)

Current Optimizations:

• ✅ Branch protection on main branch
• ✅ Required code review for pull requests
• ✅ SHA-pinned GitHub Actions
• ✅ CodeQL SAST enabled
• ✅ Dependabot alerts enabled
• ✅ SECURITY.md present
• ✅ No dangerous workflow patterns

Monitoring: View current score at OpenSSF Scorecard Dashboard

CII Best Practices (Target: Passing → Silver → Gold)

Requirements Met:

• ✅ Public version control (GitHub)
• ✅ Public issue tracker (GitHub Issues)
• ✅ LICENSE file (Apache-2.0)
• ✅ CONTRIBUTING.md with clear guidelines
• ✅ CODE_OF_CONDUCT.md
• ✅ SECURITY.md with vulnerability reporting
• ✅ Documentation in README
• ✅ Automated testing (Vitest + Playwright, ≥80% coverage)
• ✅ Static analysis (CodeQL, ESLint)
• ✅ Dependency scanning (Dependabot, npm audit)

Registration: Complete questionnaire at CII Best Practices

SLSA Level 3 (Status: ✅ Implemented)

Provenance Generation:

• ✅ Automated on releases via .github/workflows/slsa-provenance.yml
• ✅ Build attestations using actions/attest-build-provenance@v2
• ✅ SBOM generation using CycloneDX
• ✅ Artifacts uploaded to GitHub Releases

Verification: View attestations at https://github.com/Hack23/euparliamentmonitor/attestations/

SonarCloud Quality Gate

Setup Required:

1. Enable repository at SonarCloud
2. Add SONAR_TOKEN secret to GitHub repository
3. Configure quality gate thresholds (recommended: 80% coverage, A maintainability)

Workflow: Runs automatically on push to main and pull requests

FOSSA License Compliance

Setup Required:

1. Sign up at FOSSA
2. Connect GitHub repository
3. Configure license policy (Apache-2.0 compatible only)

Badge: Updates automatically after scan completion

REUSE Compliance (Status: ✅ Implemented)

Compliance Verification:

• ✅ .reuse/dep5 covers all files without headers
• ✅ Apache-2.0 license applied to all project files
• ✅ Copyright notices: "2024-2026 Hack23 AB"

Workflow: Runs on push, pull requests, and weekly via .github/workflows/reuse.yml

ISMS Policy References

This project adheres to Hack23 ISMS policies:

Policy	Relevance	Implementation
Open Source Policy	Security badge requirements	All required badges implemented
Secure Development Policy	Development security standards	SECURITY_ARCHITECTURE.md, SAST/SCA/DAST
Threat Modeling Policy	Threat analysis requirements	STRIDE analysis in SECURITY_ARCHITECTURE.md
Vulnerability Management	Remediation SLAs	SECURITY.md disclosure timeline
Classification Framework	Data classification	Public/Medium/Medium (L1/L2/L2)
Incident Response Plan	Security incident procedures	Linked in SECURITY.md

Compliance Frameworks

EU Parliament Monitor aligns with multiple compliance frameworks:

Framework	Controls	Evidence
ISO 27001	A.12.6.1 (Vulnerability Management), A.14.2.8 (Security Testing)	CodeQL, Dependabot, npm audit
NIST CSF 2.0	Identify, Protect, Detect, Respond, Recover	SECURITY_ARCHITECTURE.md compliance matrix
CIS Controls v8.1	18.3 (Remediate Vulnerabilities), 2.7 (Allowlisting)	Automated scanning, SBOM
GDPR	Data Protection by Design	European Parliament open data (public)
NIS2	Article 20, 21 (Cybersecurity Risk Management)	Threat model, security controls
EU Cyber Resilience Act	SBOM, Vulnerability Disclosure	SLSA provenance, SECURITY.md

License

Copyright 2024-2026 Hack23 AB

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See LICENSE file for full details.

Credits

This project is based on the news generation implementation from Hack23/riksdagsmonitor.

Author

Hack23 AB - Intelligence Operations Team