SW360 Architecture

SW360 Architecture Documentation

Version: 1.0
Date: March 2026
Classification: Public

Document Information

Table of Contents

1. Introduction and Goals
2. Executive Summary
3. Architecture Constraints
4. System Context
5. Solution Strategy
6. Building Block View
7. Runtime View
8. Deployment View
9. Cross-cutting Concepts
10. Architecture Decisions
11. Quality Requirements
12. Risks and Technical Debt
13. Testing Strategy
14. Glossary
15. Frontend Architecture (React UI)

1. Introduction and Goals

1.1 Purpose

SW360 is an open source software component management application designed for large organizations to track, manage, and ensure compliance of open source software components. This document provides a comprehensive architecture overview following the Arc42 template.

1.2 Goals and Requirements

Primary Goals:

• Provide centralized catalog of software components, releases, and licenses
• Enable license compliance tracking and clearing workflows
• Support vulnerability management and security tracking
• Offer REST API for integration with CI/CD pipelines and other tools
• Maintain audit trail for compliance and regulatory requirements

Key Requirements:

• Scalable to handle 100,000+ components
• Support for 100+ concurrent users
• REST API response times under 200ms
• High availability (99%+ uptime during business hours)
• Integration with external tools (FOSSology, CVE databases)

1.3 Technology Stack Overview

2. Executive Summary

2.1 What is SW360?

SW360 is an open source software component catalog designed to:

• Manage: Components, releases, licenses, projects, and vendors
• Track: Vulnerabilities (CVE), security advisories, and clearing status
• Comply: License obligations, export control, and audit requirements
• Integrate: REST API, FOSSology, CVE-Search, SBOM import/export

2.2 Essential Features

2.3 Stakeholders

2.4 Quality Goals

The top quality goals for SW360 architecture (in priority order):

2.5 Document Scope

This architecture documentation covers:

• ✅ SW360 backend services (Thrift-based)
• ✅ REST API layer
• ✅ Database layer (CouchDB)
• ✅ Authentication integration (Keycloak)
• ✅ External tool integrations (FOSSology, CVE-Search)
• ✅ Deployment architecture (Docker)
• ✅ SW360 Frontend Architecture

Out of scope:

• ❌ Legacy Liferay UI (deprecated)
• ❌ Third-party tool internal architecture

3. Architecture Constraints

This section describes the constraints that influenced the architecture decisions for SW360.

3.1 Technical Constraints

3.1.1 Programming Languages & Frameworks

3.1.2 Database

3.1.3 Authentication & Security

3.1.4 Deployment

3.2 Enterprise Environment Constraints

Legacy System Integration

• Constraint: Must integrate with existing enterprise systems (LDAP, Active Directory, existing databases)
• Impact: Required flexible authentication mechanisms and data federation capabilities
• Solution: Keycloak with pluggable user storage providers and OAuth2/OIDC standards

Compliance and Audit Requirements

• Constraint: Full audit trails required for compliance (SOX, GDPR, internal policies)
• Impact: Every data modification must be logged with user attribution and timestamps
• Solution: CouchDB’s built-in revision system and dedicated changelog database

Multi-tenancy Support

• Constraint: Multiple departments/organizations sharing same SW360 instance
• Impact: Data isolation and role-based access control at multiple levels
• Solution: Domain-driven design with clear boundaries and RBAC implementation

3.3 Performance and Scalability Constraints

Large Dataset Handling

• Constraint: Systems may contain 100,000+ components and complex dependency graphs
• Impact: Traditional RDBMS queries become inefficient for graph traversal
• Solution: CouchDB views with pre-computed indices and Lucene/Nouveau search integration

Concurrent User Load

• Constraint: 100+ simultaneous users with responsive UI requirements (<200ms response)
• Impact: Stateless architecture required with efficient caching strategies
• Solution: Stateless REST services with connection pooling and view-based caching

3.4 Organizational Constraints

3.5 Architecture Principles

The following principles guide architectural decisions:

Principle 1: Separation of Concerns

• REST layer handles HTTP concerns
• Backend services contain business logic
• Database layer handles persistence

Principle 2: Domain-Driven Design

• Core entities: Component, Release, Project, License, Vulnerability
• Bounded contexts per domain area
• Thrift definitions as domain contracts

Principle 3: API-First

• REST API is the primary interface
• OpenAPI specification for documentation
• Backward compatibility for API changes

Principle 4: Security by Design

• Role-based access control (RBAC)
• Document-level permissions
• External identity provider (Keycloak)

4. System Context

This section describes how SW360 interacts with its environment, including users, external systems, and integrations.

4.1 System Context Diagram

4.2 External Interfaces

4.2.1 User Interfaces

4.2.2 External Systems

4.3 Context Table

4.4 Network Ports

4.5 Data Flow Overview

5. Solution Strategy

This section describes the fundamental architecture decisions and solution approaches for SW360.

5.1 Technology Decisions

5.2 Why These Choices?

Java + Spring Boot

✅ Strong typing catches errors at compile time
✅ Mature ecosystem (security, testing, monitoring)
✅ Enterprise adoption ensures long-term viability
✅ Excellent IDE support for development productivity

Apache Thrift

✅ Efficient binary serialization (smaller payloads)
✅ Language-independent service contracts
✅ Strict interface definitions prevent drift
✅ Supports complex data types and nested structures

CouchDB (Document Database)

✅ Flexible schema adapts to evolving domain model
✅ Built-in replication for disaster recovery
✅ RESTful API simplifies operations
✅ MVCC prevents write conflicts
✅ Attachments stored directly in documents

5.3 Architecture Patterns

5.3.1 Layered Architecture

SW360 follows a strict layered architecture:

5.3.2 Key Design Patterns

5.3.3 Domain-Driven Design Elements

5.4 Security Strategy

5.4.1 Authentication Flow

5.4.2 Authorization Model

5.4.3 User Roles Hierarchy

5.5 Data Strategy

5.5.1 Database Design Approach

• Document-oriented: Each entity is a self-contained document
• Denormalization: Related data embedded where appropriate
• ID References: Cross-document relationships via ID fields
• Views: Pre-computed indexes for common queries
• Attachments: Binary files stored with parent documents

5.5.2 Consistency Model

6. Building Block View

This section describes the static decomposition of SW360 into modules.

6.1 Level 1: System Overview

6.2 REST Layer

Controllers and Services

Core Components

• RestControllerHelper: Common utilities for controllers (pagination, user extraction)
• JacksonCustomizations: JSON serialization mixins for Thrift objects
• RestExceptionHandler: Global exception handling with @ControllerAdvice
• ThriftClients: Factory for creating Thrift service clients

6.3 Backend Services

Handler Pattern

Each backend module follows this pattern:

• Handler (e.g., ComponentHandler): Implements Thrift service interface
• DatabaseHandler (e.g., ComponentDatabaseHandler): Business logic
• Repository (e.g., ComponentRepository): CouchDB access
• SearchHandler (optional): Full-text search implementation

6.4 Libraries

datahandler Key Components

• Thrift Definitions (src/main/thrift/): All entity definitions
• CouchDB Client (cloudantclient/): Database access layer
• Common Utilities (common/): SW360Utils, CommonUtils, SW360Assert
• Permissions (permissions/): Document-level permission checking

6.5 Keycloak Integration

6.6 Data Model

Core Entities

Entity Relationships

• Component 1:N Release (one component has many releases)
• Project N:M Release (projects link to releases)
• Release N:M License (releases have licenses)
• License N:M Obligation (licenses have obligations)
• Release N:M Vulnerability (releases affected by vulnerabilities)
• Component N:1 Vendor (components have one vendor)

6.7 Thrift Service Architecture

7. Runtime View

This section describes the behavior of the system at runtime through important use cases and scenarios.

7.1 Component Creation Flow

Note: Search indexing occurs asynchronously - CouchDB’s view update mechanism notifies Nouveau directly, not through the SW360 application.

7.2 Authentication Flow (JWT)

7.3 Clearing Request Workflow

7.4 Vulnerability Synchronization

7.5 SBOM Import Flow

7.6 API Caching Flow

SW360 implements a file-based API response cache for resource-intensive endpoints like GET /releases?allDetails=true. This caching mechanism avoids JVM heap pressure by storing pre-serialized JSON responses on disk.

Key Design Decisions:

Reference: See ADR-007: File-Based API Response Cache for detailed rationale and implementation guidance.

8. Deployment View

This section describes the infrastructure and deployment architecture of SW360.

8.1 Deployment Overview

8.2 Container Specification

8.2.1 SW360 Application Container

Environment Variables:

8.2.2 CouchDB Container

Databases:

8.2.3 Keycloak Container

8.3 Docker Compose Configuration

# docker-compose.yml (simplified)
services:
  sw360:
    image: ghcr.io/eclipse-sw360/sw360:latest
    ports:
      - "8080:8080"
      - "11311:11311"
    depends_on:
      - couchdb
    volumes:
      - etc:/etc/sw360
      - ./config/sw360:/app/sw360/config
    environment:
      - SW360_BASE_URL=http://localhost:8080

  couchdb:
    image: couchdb:3.4
    ports:
      - "5984:5984"
    volumes:
      - couchdb:/opt/couchdb/data
      - ./config/couchdb/sw360_setup.ini:/opt/couchdb/etc/local.d/sw360_setup.ini

  couchdb-nouveau:
    image: couchdb:3.4-nouveau
    ports:
      - "5987:5987"
      - "5988:5988"

volumes:
  couchdb:
  etc:

networks:
  default:
    name: sw360net

8.4 Production Deployment Considerations

8.4.1 High Availability Architecture

Load Balancing: CouchDB cluster deployments require a load balancer (e.g., HAProxy, nginx) in front of cluster nodes to distribute client requests and provide failover.

8.4.2 Scaling Guidelines

8.4.3 Minimum Requirements

8.5 Configuration Files

For detailed configuration file reference, see the existing deployment documentation:
👉 Deploy Configuration Files

8.6 Deployment Checklist

Pre-deployment

• CouchDB databases created and initialized
• Keycloak realm and client configured
• SSL certificates provisioned
• Secrets managed (Vault, K8s secrets, etc.)
• Network firewall rules configured

Post-deployment

• Health endpoint responding (/health)
• Authentication working (Keycloak login)
• Database connectivity verified
• API endpoints accessible
• Scheduled tasks running (CVE sync)
• Logging configured and working

8.7 Infrastructure as Code (IaC)

For reproducible and version-controlled deployments, SW360 infrastructure can be defined using IaC tools:

IaC Principles:

• Store infrastructure definitions in version control
• Use parameterized templates for environment-specific values
• Implement CI/CD for infrastructure changes
• Maintain separate configurations for dev/staging/production

9. Cross-cutting Concepts

This section describes cross-cutting technical concepts that apply across the entire SW360 system.

9.1 Security Concepts

9.1.1 Authentication

SW360 supports multiple authentication mechanisms:

9.1.2 Authorization Model

9.1.3 User Roles

9.1.4 Document Visibility

enum Visibility {
    PRIVATE,                    // Only creator
    ME_AND_MODERATORS,          // Creator + moderators
    BUISNESSUNIT_AND_MODERATORS,// Same business unit
    EVERYONE                    // All authenticated users
}

9.2 Persistence Concepts

9.2.1 CouchDB Design Principles

9.2.2 Repository Pattern

// Base repository class
public class ComponentRepository extends DatabaseRepositoryCloudantClient<Component> {
    
    public ComponentRepository(DatabaseConnectorCloudant db) {
        super(db, Component.class);
        initStandardDesignDocument(getViews(), db);
    }
    
    // Query using CouchDB views
    public List<Component> getByName(String name) {
        return queryView("byName", name);
    }
    
    // Query using Mango selectors
    public List<Component> getByType(ComponentType type) {
        Map<String, Object> selector = eq("componentType", type.name());
        return db.queryBySelector(selector, Component.class);
    }
}

9.2.3 Query Operators

import static org.eclipse.sw360.datahandler.cloudantclient.DatabaseConnectorCloudant.*;

// Equality
eq("field", "value")

// In list
in("field", List.of("a", "b", "c"))

// Exists
exists("field", true)

// Logical operators
and(condition1, condition2)
or(condition1, condition2)

// Element match (arrays)
elemMatch("releases", eq("clearingState", "APPROVED"))

9.3 API Design Concepts

9.3.1 REST Conventions

9.3.2 HATEOAS Links

HATEOAS (Hypermedia as the Engine of Application State) is a REST constraint that enables clients to navigate the API dynamically through hyperlinks embedded in responses. Rather than hardcoding API endpoints, clients discover available actions from the _links object returned with each resource. This decouples client logic from server URL structure, enabling API evolution without breaking clients.

{
  "name": "My Project",
  "_links": {
    "self": { "href": "/api/projects/abc123" },
    "sw360:releases": { "href": "/api/projects/abc123/releases" },
    "sw360:attachments": { "href": "/api/projects/abc123/attachments" },
    "curies": [{ "name": "sw360", "href": "/docs/{rel}.html" }]
  },
  "_embedded": {
    "sw360:releases": [...]
  }
}

9.4 Error Handling

9.4.1 Exception Hierarchy

Exception
├── SW360Exception (Thrift layer)
│   └── errorCode: 400, 403, 404, 409, 500
├── ResourceNotFoundException (REST)
├── AccessDeniedException (REST)
├── BadRequestClientException (REST)
└── DataIntegrityViolationException (REST)

9.4.2 Global Exception Handler

@ControllerAdvice
public class RestExceptionHandler {
    
    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ErrorResponse> handleNotFound(ResourceNotFoundException ex) {
        return ResponseEntity.status(404).body(
            new ErrorResponse(404, "Not Found", ex.getMessage())
        );
    }
    
    @ExceptionHandler(AccessDeniedException.class)
    public ResponseEntity<ErrorResponse> handleAccessDenied(AccessDeniedException ex) {
        return ResponseEntity.status(403).body(
            new ErrorResponse(403, "Forbidden", ex.getMessage())
        );
    }
}

9.5 Logging

9.5.1 Logging Standards

9.5.2 Structured Logging

// Good: Parameterized logging
log.info("Processing {} releases for project {}", count, projectId);

// Bad: String concatenation
log.info("Processing " + count + " releases for project " + projectId);

9.6 Validation

9.6.1 Input Validation

import static org.eclipse.sw360.datahandler.common.SW360Assert.*;

public void createComponent(Component component, User user) throws SW360Exception {
    // Validate inputs
    assertNotNull(component, "Component cannot be null");
    assertNotEmpty(component.getName(), "Component name is required");
    assertUser(user);
    
    // Business validation
    if (componentExists(component.getName())) {
        throw new SW360Exception("Component already exists")
            .setErrorCode(409);
    }
}

10. Architecture Decisions

This section documents key architecture decisions using the ADR (Architecture Decision Record) format.

ADR-001: Use Apache Thrift for Internal Services

Rationale:

1. Efficient Binary Protocol: Thrift’s binary protocol is more compact than JSON/XML
2. Interface Definition Language (IDL): Formal contracts between services
3. Code Generation: Generates strongly-typed Java classes
4. Complex Data Structures: Native support for nested structs, maps, sets, lists
5. Cross-Language Support: Supports Python, C++, PHP for future integration

Consequences:

• ✅ Strong typing, performance, clear contracts, backward compatibility
• ❌ Learning curve, build complexity, debugging difficulty

ADR-002: Use CouchDB as Primary Database

Rationale:

1. Schema Flexibility: Documents can have different structures without migrations
2. Attachment Storage: Binary attachments stored directly with documents
3. RESTful HTTP API: Simple integration without special drivers
4. Replication: Built-in master-master replication for disaster recovery
5. MVCC: Optimistic locking via _rev field prevents concurrent update conflicts

Consequences:

• ✅ Flexible data model, attachment handling, HTTP API, replication
• ❌ No SQL joins, eventual consistency, query limitations

ADR-003: Use Keycloak for Authentication

Rationale:

1. Open Source & Self-Hosted: No vendor lock-in, full control over user data
2. Enterprise Features: LDAP/AD federation, SAML 2.0, OIDC, MFA
3. Standard Protocols: OAuth 2.0 for API authentication, OIDC for identity
4. Customization: Custom user storage providers, event listeners
5. Active Community: Red Hat backing, regular security updates

Consequences:

• ✅ SSO support, JWT tokens, federation, security, API tokens
• ❌ Additional component to maintain, OAuth2 complexity

ADR-004: Migrate to Spring Boot 3.x

Rationale:

1. Long-term Support: Spring Boot 3.x is actively maintained
2. Security Improvements: Spring Security 6 includes enhanced OAuth2 support
3. Performance: Java 21 virtual threads, improved GC
4. Modern APIs: Records, pattern matching, sealed classes
5. Ecosystem: Latest versions of SpringDoc, Jackson, etc.

Key Changes:

• Namespace migration: javax.* → jakarta.*
• Security configuration: New DSL, authorization changes
• OpenAPI/SpringDoc: Version upgrade, annotation changes

ADR-005: Use Apache Tomcat as Servlet Container

Rationale:

1. Liferay Compatibility: Liferay portal required a servlet container
2. Multiple Web Applications: Tomcat supports deployment of individual WAR files
3. Industry Standard: Widely adopted, well-documented, production-proven
4. Spring Boot Integration: Embedded Tomcat in Spring Boot 3.x (Tomcat 11.x)

Consequences:

• ✅ Standard servlet deployment, mature ecosystem, excellent documentation
• ❌ Additional configuration for performance tuning

ADR-006: Migrate to Cloudant SDK for CouchDB Access

Rationale:

1. Ektorp Deprecation: Original CouchDB client library no longer maintained
2. IBM Corporate Support: IBM unified their cloud support SDKs, backing active development
3. CouchDB Compatibility: Cloudant SDK works with standard CouchDB (not just IBM Cloudant)
4. Modern Java Support: Full Java 21 compatibility and async operations

Consequences:

• ✅ Active maintenance, corporate backing, modern API
• ❌ API migration effort, IBM branding (though works with any CouchDB)

11. Quality Requirements

This section describes the quality requirements for SW360 and how the architecture addresses them.

11.1 Quality Tree

11.2 Quality Scenarios

11.2.1 Performance

11.2.2 Security

11.2.3 Scalability

11.3 Quality Measures

11.3.1 Code Quality

11.3.2 Operational Quality

11.4 Quality Trade-offs

12. Risks and Technical Debt

This section documents known risks and technical debt in the SW360 architecture.

12.1 Technical Risks

12.1.1 High Priority Risks

12.1.2 Medium Priority Risks

12.2 Technical Debt

12.2.1 High Priority Debt

12.2.2 Medium Priority Debt

12.3 Risk Monitoring

12.3.1 Key Metrics to Watch

12.4 Debt Reduction Plan

Short-term (Next Release)

• Standardize error responses
• Add missing pagination
• Update documentation

Medium-term (6 months)

• Increase test coverage to 70%
• Remove legacy Liferay code
• Implement comprehensive logging

Long-term (12+ months)

• Evaluate microservices architecture
• Consider caching layer
• Implement webhooks/async processing

13. Testing Strategy

This section describes the testing approach for SW360, following the Testing Trophy methodology.

13.1 Current State vs Target State

13.2 Test Pyramid vs Testing Trophy

Test Pyramid (Traditional)

                    /\
                   /  \      E2E Tests (Few, Slow, Expensive)
                  /----\
                 /      \    Integration Tests (Some)
                /--------\
               /          \  Unit Tests (Many, Fast, Cheap)
              --------------

Testing Pyramid (SW360 Approach)

13.3 Test Level Breakdown

13.4 Key Testing Principles

1. Test behavior at the REST layer — that’s what users consume
2. Static analysis is free testing — maximize it (Spotless, SpotBugs, ArchUnit)
3. Unit test complex logic only — not glue code
4. E2E tests are expensive — use sparingly for critical paths
5. If you mock too much, test at a higher level
6. Refactoring should not break tests — if it does, tests are too coupled

13.5 Recommended Tools

13.6 Critical User Journeys for E2E

1. Authentication Flow: Login → Access protected resource → Logout
2. Component Lifecycle: Create Component → Add Release → Upload Source → Trigger Clearing
3. Project Clearing: Create Project → Link Releases → Generate Clearing Report
4. License Compliance: Search License → Check Obligations → Export Report

14. Glossary

This section defines terms used throughout the SW360 architecture documentation.

14.1 Domain Terms

14.2 Technical Terms

14.3 Standards and Specifications

14.4 Abbreviations

15. Frontend Architecture (React UI)

For the full frontend architecture documentation, see the dedicated document:
👉 SW360 Frontend Architecture

Appendix A: Revision History

Appendix B: References

1. Arc42 Template: https://arc42.org/
2. Eclipse SW360: https://eclipse.dev/sw360/
3. Apache CouchDB: https://couchdb.apache.org/
4. Apache Thrift: https://thrift.apache.org/
5. Keycloak: https://www.keycloak.org/
6. Spring Boot: https://spring.io/projects/spring-boot
7. SPDX Specification: https://spdx.dev/
8. CycloneDX Specification: https://cyclonedx.org/

This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which is available at https://www.eclipse.org/legal/epl-2.0/