Overview

Relevant source files

• .github/dependabot.yml
• README.md
• cia-dist-cloudformation/pom.xml
• cia-dist-cloudformation/src/main/resources/README.txt
• cia-dist-cloudformation/src/main/resources/cia-dist-cloudformation.json
• cia-dist-cloudformation/src/main/resources/cia-dist-cloudformation.yml
• cia-dist-deb/pom.xml
• citizen-intelligence-agency/pom.xml
• encrypt.properties/pom.xml
• jms-broker/pom.xml
• model.common.impl/pom.xml
• model.external.worldbank.countries.impl/pom.xml
• model.internal.application.user.impl/pom.xml
• parent-model-external-pom/pom.xml
• parent-model-internal-pom/pom.xml
• parent-model-jpa2-pom/pom.xml
• parent-model-pom/pom.xml
• parent-pom/pom.xml
• parent-service-pom/pom.xml
• parent-web-pom/pom.xml
• pom.xml
• service.component.agent.impl/pom.xml
• service.data.impl/pom.xml
• service.external.common/pom.xml
• service.external.esv/pom.xml
• service.external.riksdagen/pom.xml
• service.external.val/pom.xml
• service.external.worldbank/pom.xml
• service.impl/pom.xml
• testfoundation/pom.xml
• web-widgets/pom.xml

Purpose and Scope

The Citizen Intelligence Agency (CIA) is an open-source intelligence (OSINT) platform for monitoring and analyzing Swedish political activity. This document provides a high-level overview of the system architecture, technology stack, and major components. For detailed information about specific subsystems, see:

• Architecture details: System Overview
• Maven module organization: Maven Module Structure
• Development environment setup: Local Development Setup
• Deployment strategies: Deployment Options Overview

The system is implemented as a Maven multi-module Java project using a three-tier architecture with Spring Framework for business logic, Vaadin for the web interface, and PostgreSQL for data persistence. It integrates with four Swedish government data sources (Riksdagen, ESV, WorldBank, Val) and deploys to AWS infrastructure or as a standalone Debian package.

Sources: README.md1-15 parent-pom/pom.xml1-46

System Architecture

The CIA platform follows a modular, layered architecture organized through Maven's multi-module project structure. The system aggregates political data from external Swedish government APIs, processes it through a service layer with business rules, persists it in PostgreSQL with full-text search capabilities, and presents it through an interactive Vaadin web interface.

Maven Module Hierarchy

The project root is defined in parent-pom with artifact ID com.hack23.cia and contains six top-level modules that organize the codebase into logical layers. Each parent POM manages dependencies and build configuration for its child modules.

Sources: parent-pom/pom.xml39-46 parent-service-pom/pom.xml26-39 parent-web-pom/pom.xml26-30

Technology Stack

Framework Versions and Dependencies

The technology stack is defined centrally in parent-pom/pom.xml using Maven dependency management. Key version properties include:

Component	Version Property	Version
Java	jdk.src.version	21
Spring Framework	cia.project.versions.spring	5.3.39.hack23java25
Spring Security	cia.project.versions.spring.security	5.8.16
Hibernate	cia.project.versions.hibernate	5.6.15.Final
Vaadin	cia.project.versions.vaadin	8.14.4
PostgreSQL JDBC	cia.project.versions.postgresql	42.7.10
Drools	cia.project.versions.drools	10.1.0
Jetty	cia.project.versions.jetty	10.0.26

Sources: parent-pom/pom.xml83-158 citizen-intelligence-agency/pom.xml1-13 service.data.impl/pom.xml1-14

Core Component Architecture

Component Responsibilities

The system implements a clear separation of concerns across layers:

Web Layer (citizen-intelligence-agency, web-widgets):

• Vaadin UI framework integration with Spring
• Custom widget components for data visualization
• Session management and user authentication flow
• Responsive layout components for dashboard presentation

Service Layer (service.impl):

• ApplicationManager interface defines the public service API
• Spring Security integration for authentication (Google Authenticator 2FA)
• Drools rules engine for business logic evaluation
• Quartz scheduler for periodic data import jobs

Data Access Layer (service.data.impl):

• Spring Data JPA repositories for CRUD operations
• Hibernate as the JPA provider with entity management
• Hibernate Search with Lucene for full-text indexing
• Javers for entity versioning and audit trails
• Liquibase manages 75 schema changesets for database evolution

Import Agents (service.component.agent.impl):

• Background jobs triggered by Quartz scheduler
• Asynchronous JMS messaging via Apache Artemis
• Integration with four external data source clients
• Error handling and retry logic for resilient data import

Sources: citizen-intelligence-agency/pom.xml10-13 service.impl/pom.xml10-13 service.data.impl/pom.xml10-13 service.component.agent.impl/pom.xml10-13

Data Flow and Processing

Data Processing Pipeline

The data flow follows a multi-stage pipeline from external APIs to database persistence:

1. Scheduled Import: Quartz triggers agents defined in service.component.agent.impl at configured intervals
2. External API Calls: Clients use JAXB for XML (Riksdagen, Val), POI for Excel (ESV), and Jackson for JSON (WorldBank)
3. Asynchronous Messaging: Apache Artemis JMS broker decouples data ingestion from processing
4. Business Rules: Drools rules engine applies validation and transformation logic
5. Persistence: Hibernate/JPA persists entities to PostgreSQL with automatic schema management via Liquibase
6. Full-Text Indexing: Hibernate Search maintains Lucene indexes for searchable fields
7. Audit Trail: Javers tracks entity changes for compliance and history
8. View Materialization: Database triggers refresh 107 analytical views and 2 materialized views

Sources: service.component.agent.impl/pom.xml1-14 jms-broker/pom.xml10-14 service.impl/pom.xml10-13 service.data.impl/pom.xml122-175

Deployment Architecture

Deployment Options

The system provides two primary deployment strategies:

AWS CloudFormation Deployment:

• Infrastructure-as-code templates in cia-dist-cloudformation module
• Provisions VPC with 3 availability zones for high availability
• EC2 Auto Scaling Group runs c7g.2xlarge ARM64 instances (Ubuntu 20.04)
• RDS PostgreSQL Multi-AZ with automated backups and encryption
• Application Load Balancer with SSL/TLS termination
• Systems Manager for automated patching via maintenance windows
• Default Debian package URL: https://github.com/Hack23/cia/releases/download/2025.1.2/cia-dist-deb-2025.1.2.all.deb

Debian Package Deployment:

• Self-contained DEB package created by cia-dist-deb module using unix-maven-plugin
• Includes Jetty 10.0.26 server with HTTP/2 and WebSocket support
• Packaged WAR file deployed to Jetty webapps directory
• SSL/TLS certificates generated via keytool-maven-plugin (PKCS12 keystore)
• Systemd service integration for automatic startup
• Environment configuration via /etc/default/cia

Build Artifacts:

• Maven produces the WAR artifact in citizen-intelligence-agency/target/
• Debian package assembly copies WAR and Jetty distribution
• CycloneDX and SPDX SBOM generation for supply chain security
• CloudFormation templates support both JSON and YAML formats

Sources: cia-dist-cloudformation/src/main/resources/cia-dist-cloudformation.yml1-98 cia-dist-cloudformation/src/main/resources/cia-dist-cloudformation.json1-118 cia-dist-deb/pom.xml1-46

Development Environment

The project includes a Dev Container configuration for reproducible development environments. The container provides:

• Base Image: mcr.microsoft.com/devcontainers/java:21 with Maven 3.9.9
• Database: PostgreSQL 16 with cia_dev database, user eris, SSL certificates
• Build Tools: Apache Ant for task automation, xvfb for headless browser testing
• VS Code Tasks: Pre-configured tasks for running the server, executing tests, and clean installs
• Port Forwarding: Automatic forwarding of port 8443 (HTTPS) and 5432 (PostgreSQL)

The dev container automatically initializes the database schema using Liquibase changesets and configures performance tuning parameters for development workloads.

Sources: README.md1-15 parent-pom/pom.xml162-171

Security Architecture

The system implements defense-in-depth security across multiple layers:

Network Security:

• VPC isolation with public, private application, and private database subnets
• Network ACLs and security groups restrict traffic flow
• AWS WAF provides web application firewall protection
• VPC Flow Logs capture network traffic for analysis

Application Security:

• Spring Security 5.8.16 for authentication and authorization
• Google Authenticator integration for two-factor authentication (TOTP)
• Passay password policy enforcement (complexity, history, expiration)
• Session management with timeout and concurrent session control

Data Security:

• KMS encryption for RDS at rest and S3 bucket encryption
• SSL/TLS 1.2+ for all data in transit (database, ALB, inter-service)
• AWS Secrets Manager for credential storage with automatic rotation
• Javers audit trail for entity change tracking (compliance)

Build Security:

• GitHub Actions workflows for CodeQL SAST, dependency scanning, OSSF Scorecard
• ZAP DAST for runtime security testing
• Snyk container scanning for Docker images
• SLSA provenance and SBOM attestations for supply chain security

Sources: service.impl/pom.xml139-158 cia-dist-cloudformation/src/main/resources/cia-dist-cloudformation.yml210-270