Architecture

Overview

Bauhaus is a modern web application built with React that communicates with a backend services ecosystem to manage statistical metadata and documents.

Architecture Diagram

graph TB
    Users[Users]

    subgraph Frontend["Bauhaus Frontend (React)"]
        React["React 18<br/>TypeScript<br/>TanStack Query<br/>PrimeReact UI Components<br/>react-i18next"]
    end

    subgraph Backend["Bauhaus Back-Office API (Spring Boot)"]
        SpringBoot["Spring Boot<br/>Spring Security + OAuth2<br/>REST Controllers"]
    end

    subgraph Security["Identity & Access Management"]
        Keycloak["Keycloak (IAM)<br/>Authentication<br/>Authorization (SSO)<br/>User and role management<br/>OAuth2 / OpenID Connect"]
    end

    subgraph Storage["File Storage"]
        MinIO["MinIO (Object Storage)<br/>File storage<br/>PDF documents, images, etc.<br/>S3-compatible API"]
    end

    subgraph Database["RDF Database"]
        GraphDB["GraphDB<br/>Triple store<br/>Ontologies and reference data<br/>SPARQL Endpoint"]
    end

    subgraph Metadata["DDI Metadata"]
        Colectica["Colectica Repository API<br/>DDI Lifecycle Manager<br/>Statistical metadata"]
    end

    Users -->|HTTPS| Frontend
    Frontend -->|REST API / HTTP| Backend
    Backend -->|OAuth2 / OIDC| Keycloak
    Backend -->|SPARQL / RDF| GraphDB
    Backend -->|S3 Protocol| MinIO
    Backend -->|REST API| Colectica

    style Users fill:#e1f5ff
    style Frontend fill:#fff4e1
    style Backend fill:#e8f5e9
    style Keycloak fill:#fce4ec
    style MinIO fill:#f3e5f5
    style GraphDB fill:#e0f2f1
    style Colectica fill:#fff9c4

Main Components

Frontend - Bauhaus

React single-page application (SPA) that provides the user interface for managing statistical metadata.

Key Technologies:

• React 18, 100% TypeScript, function components only
• TanStack Query for server state (no global client-side state library)
• PrimeReact for UI components
• Vite as bundler
• react-i18next for internationalization (see Internationalization)
• oxlint + oxfmt for linting and formatting, knip for dead-code detection (run in pnpm pre-push)

React Documentation | Redux Documentation

Backend - Spring Boot API

REST API that orchestrates all backend services and exposes business functionalities.

Responsibilities:

• Orchestration of calls to different services
• Business logic
• Data validation and transformation
• Security management

Spring Boot Documentation

Security - Keycloak

Identity and Access Management (IAM) server that secures the entire stack.

Features:

• Single Sign-On (SSO)
• User and role management
• OAuth2 and OpenID Connect protocols
• Identity federation

Keycloak Documentation

File Storage - MinIO

S3-compatible object storage server for managing documents and files.

Use Cases:

• PDF document storage
• Images and graphics
• Data files
• Amazon S3-compatible API

MinIO Documentation

RDF Database - GraphDB

Triple store for storing and querying semantic data.

Use Cases:

• Ontology storage
• Metadata reference data
• Semantic relationships
• SPARQL queries

GraphDB Documentation

DDI Metadata - Colectica Repository

Statistical metadata manager based on the DDI (Data Documentation Initiative) standard.

Features:

• Metadata lifecycle management
• DDI Lifecycle standard support
• Metadata versioning
• REST API for programmatic access

Colectica Documentation | DDI Standard

Data Flows

Authentication

1. User accesses Bauhaus Frontend
2. Redirect to Keycloak for authentication
3. Keycloak validates credentials and issues a JWT token
4. Frontend stores the token and sends it with each API request
5. Spring Boot backend validates the token with Keycloak

Metadata Retrieval

1. Frontend makes a REST request to the backend
2. Backend queries:
   • GraphDB for reference data and classifications (via SPARQL)
   • Colectica for DDI metadata (via REST API)
3. Backend aggregates and transforms the data
4. JSON response returned to the frontend

Document Management

1. Document upload from the frontend
2. Backend validates and processes the file
3. File storage in MinIO via S3 API
4. Document metadata stored in GraphDB
5. Reference returned to the frontend

Frontend Code Architecture

The frontend has completed its migration to a modern, standardized stack. All 7 domain modules (concepts, classifications, operations, codelists, structures, datasets, ddi) follow the same target architecture.

Technical stack

Concern	Technology
Language	TypeScript — the codebase is 100% .ts/.tsx
Components	Function components only
Module exports	Named exports project-wide
UI components	PrimeReact
Styling	Plain CSS co-located with components, CSS variables (--color-1, --color-2, …)
Internationalization	react-i18next — see Internationalization
Testing	Vitest, .spec.ts(x) co-located with source
Forms	Native HTML forms with FormData API
Linting / formatting	oxlint + oxfmt (replacing ESLint + Prettier)
Dead-code detection	knip, run automatically in pnpm pre-push

Conventions

When working on the codebase:

1. Component organization — extract reusable components into dedicated files with co-located styles and tests
2. I18N — use react-i18next’s useTranslation() hook; each module owns an isolated i18next instance (never the raw global singleton), configured at the module level via the layout component
3. UI components — prefer PrimeReact over Bootstrap
4. Styling — use CSS files co-located with components, leverage CSS variables (--color-1, --color-2, …)
5. Forms — use native HTML forms with FormData API and proper submit buttons; validate with zod in a co-located validation.ts
6. Testing — write unit tests for all new components using Vitest; mock PrimeReact components when needed
7. Exports — use named exports; avoid re-export-only (“pass-through”) files unless they are genuine barrel files

See Project Structure for the expected module directory layout and I18N setup.

Learn More

• Getting Started - Developer getting started guide
• Project Structure - Module layout, I18N, and form validation reference
• Colectica API Reference - Calls exchanged with Colectica Repository
• Overview — Variables Module - The module built on top of Colectica
• Bauhaus Back-Office - Backend GitHub repository