SW360 Frontend Architecture

SW360 Frontend Architecture Documentation

Version: 1.0
Date: May 2026
Classification: Public
Repository: eclipse-sw360/sw360-frontend

Document Information

Table of Contents

1. Introduction and Goals
2. Technology Stack
3. Architecture Constraints
4. System Context
5. Building Block View
6. Runtime View
7. Deployment View
8. Cross-cutting Concepts
9. Quality Requirements
10. Risks and Technical Debt

1. Introduction and Goals

1.1 Purpose

The SW360 Frontend is a modern web application that replaces the legacy Liferay Portal UI. Built with Next.js and React, it provides a responsive, internationalized user interface for managing software components, licenses, projects, and compliance workflows.

1.2 Goals

• Modern UX: Responsive, accessible interface using React Bootstrap
• Performance: Server-side rendering (SSR) and Turbopack for fast builds
• Internationalization: 10 language support out of the box
• Security: OAuth2/OIDC authentication, CSP headers, RBAC middleware
• Separation of Concerns: Standalone frontend communicating exclusively via REST API
• Developer Experience: TypeScript, Biome linting, Playwright E2E testing

1.3 Stakeholders

2. Technology Stack

3. Architecture Constraints

3.1 Technical Constraints

3.2 Organizational Constraints

4. System Context

4.1 Context Diagram

4.2 External Interfaces

4.3 Authentication Providers

The frontend supports three authentication modes configured via NEXT_PUBLIC_SW360_AUTH_PROVIDER:

5. Building Block View

5.1 Project Structure

5.2 Layer Architecture

5.3 Key Modules

5.3.1 Pages (src/app/[locale]/)

Pages follow the SW360 domain model. Each page directory maps to a backend resource:

5.3.2 Components (src/components/)

Shared UI components organized by domain concern:

5.3.3 Object Types (src/object-types/)

TypeScript interfaces mirroring the backend Thrift/REST data model:

5.3.4 Services (src/services/)

5.3.5 Custom Hooks (src/hooks/)

6. Runtime View

6.1 Authentication Flow

6.2 Middleware Pipeline

Route Protection Configuration:

6.3 API Communication Pattern

The frontend uses a consistent pattern for data fetching:

1. Page renders and calls a custom hook
2. Hook invokes API utility with auth headers from session
3. API Utils makes fetch request to SW360 REST API
4. Response returns HAL+JSON with _embedded, _links, and page metadata
5. Data is rendered using @tanstack/react-table for list views

6.4 Notification Flow (RxJS)

Toast notifications use an RxJS Subject-based pattern:

• Action triggers message.service.ts which emits on an RxJS Subject
• Toast Component subscribes to the Observable stream and displays notifications
• This decouples business logic from UI rendering of notifications

7. Deployment View

7.1 Docker Architecture

7.2 Dockerfile (Multi-stage Build)

Build-time Environment Variables:

Runtime Environment Variables:

7.3 Docker Compose

services:
  sw360-frontend:
    build:
      context: .
      args:
        - NEXT_PUBLIC_SW360_API_URL=http://sw360:8080
        - NEXT_PUBLIC_SW360_AUTH_PROVIDER=keycloak
    ports:
      - "3000:3000"
    environment:
      - SW360_KEYCLOAK_CLIENT_ID=sw360-frontend
      - SW360_KEYCLOAK_CLIENT_SECRET=${KC_SECRET}
      - AUTH_ISSUER=http://keycloak:8083/realms/sw360
      - AUTH_SECRET=${AUTH_SECRET}
    depends_on:
      - sw360
      - keycloak

7.4 Production Considerations

8. Cross-cutting Concepts

8.1 Internationalization (i18n)

SW360 Frontend supports 10 locales using next-intl:

Architecture:

• URL-based locale: /{locale}/components (e.g., /en/components, /de/components)
• Message files: messages/{locale}.json
• Middleware detects locale from URL, cookie, or Accept-Language header
• All UI strings externalized — no hardcoded text in components

8.2 Security

8.2.1 Content Security Policy

The next.config.ts enforces strict CSP headers:

default-src 'self';
script-src 'self' 'unsafe-inline';
style-src 'self' 'unsafe-inline';
img-src 'self' data: https://secure.gravatar.com;
connect-src 'self';
object-src 'none';
frame-ancestors 'self';
require-trusted-types-for 'script';

8.2.2 Additional Security Headers

8.2.3 Role-Based Access Control (Three-Layer Defense)

SW360 Frontend implements a comprehensive RBAC system with three layers of defense:

Blacklist-Based Route Protection

The middleware uses a blockedRoles configuration with longest-prefix matching:

const roleBasedAccessControl = {
    '/admin': { roles: [ADMIN, SW360_ADMIN], authRequired: true },
    '/projects/add': { blockedRoles: [UserGroupType.VIEWER], authRequired: true },
    '/components/add': { blockedRoles: [UserGroupType.VIEWER], authRequired: true },
    '/vulnerabilities': { blockedRoles: [UserGroupType.VIEWER], authRequired: true },
    '/ecc': { blockedRoles: [UserGroupType.VIEWER], authRequired: true },
    // ... all authenticated routes
}

Capability-Based Permission System

Beyond role-based blocking, granular capabilities provide fine-grained UI control:

Component Patterns

// Layer 2: Page-level blocking via HOC
export default AccessControl(MyPage, [UserGroupType.VIEWER])

// Layer 3a: Element hiding for VIEWER
<ViewerGate>
  <Button>Edit</Button>  {/* Hidden for VIEWER */}
</ViewerGate>

// Layer 3b: Capability-based control
const { hasCapability } = usePermissionContext()
const canEdit = hasCapability('canEditClearingRequestDetails')
<input disabled={!canEdit} />

Key Infrastructure Files

8.3 State Management

SW360 Frontend uses no global state library (no Redux, Zustand, etc.). Instead:

8.4 Data Table Pattern

All list pages use @tanstack/react-table with:

• Server-side pagination (via HAL page metadata)
• Column sorting
• Row selection
• Custom cell renderers for links, badges, status icons

8.5 Error Handling

8.6 Code Quality

9. Quality Requirements

9.1 Performance

Optimization strategies:

• Next.js SSR for initial load
• Turbopack for fast development builds
• Standalone output (minimal production footprint)
• react: 19.x with concurrent features

9.2 Accessibility

9.3 Browser Support

10. Risks and Technical Debt

10.1 Risks

10.2 Technical Debt

Appendix A: Revision History

Appendix B: References

1. SW360 Frontend Repository: https://github.com/eclipse-sw360/sw360-frontend
2. Next.js Documentation: https://nextjs.org/docs
3. NextAuth.js: https://next-auth.js.org/
4. React Bootstrap: https://react-bootstrap.github.io/
5. next-intl: https://next-intl.dev/
6. TanStack Table: https://tanstack.com/table
7. Biome: https://biomejs.dev/
8. Playwright: https://playwright.dev/

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/