Skip to content

Commit aeadcb3

Browse files
rkouererkouere
authored
Merge pull request #1367 from InseeFr/4.16.0
feat: 4.16.0
2 parents d8e9805 + 339b992 commit aeadcb3

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+2566
-593
lines changed

‎documentation/astro.config.mjs‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
import { defineConfig } from 'astro/config';
22
import starlight from '@astrojs/starlight';
3+
import mermaid from 'astro-mermaid';
34

45
// https://astro.build/config
56
export default defineConfig({
67
base: 'Bauhaus',
78
trailingSlash: 'always',
89
integrations: [
10+
mermaid(),
911
starlight({
1012
title: 'Bauhaus',
1113

@@ -23,10 +25,19 @@ export default defineConfig({
2325
label: 'Developer Guide',
2426
items: [
2527
// Each item here is one entry in the navigation menu.
28+
2629
{
2730
label: 'Getting Started',
2831
link: import.meta.env.BASE_URL + 'guides/getting-started/',
2932
},
33+
{
34+
label: 'Architecture',
35+
link: import.meta.env.BASE_URL + 'guides/architecture/',
36+
},
37+
{
38+
label: 'Colectica Integration',
39+
link: import.meta.env.BASE_URL + 'guides/colectica/',
40+
},
3041
{
3142
label: 'Conventional Commits',
3243
link: import.meta.env.BASE_URL + 'guides/conventional_commit/',

‎documentation/package.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,8 @@
1313
"@astrojs/check": "^0.8.0",
1414
"@astrojs/starlight": "^0.30.6",
1515
"astro": "^5.1.3",
16+
"astro-mermaid": "^1.1.0",
17+
"mermaid": "^11.12.1",
1618
"typescript": "^5.7.2",
1719
"zod": "^3.25.76"
1820
},

‎documentation/src/content/docs/guides/architecture.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: Architecture
3+
description: Technical architecture overview of Bauhaus
4+
---
5+
6+
## Overview
7+
8+
Bauhaus is a modern web application built with React that communicates with a backend services ecosystem to manage statistical metadata and documents.
9+
10+
## Architecture Diagram
11+
12+
```mermaid
13+
graph TB
14+
Users[Users]
15+
16+
subgraph Frontend["Bauhaus Frontend (React)"]
17+
React["React 18 + Redux<br/>TypeScript<br/>PrimeReact UI Components<br/>react-i18next"]
18+
end
19+
20+
subgraph Backend["Bauhaus Back-Office API (Spring Boot)"]
21+
SpringBoot["Spring Boot<br/>Spring Security + OAuth2<br/>REST Controllers"]
22+
end
23+
24+
subgraph Security["Identity & Access Management"]
25+
Keycloak["Keycloak (IAM)<br/>Authentication<br/>Authorization (SSO)<br/>User and role management<br/>OAuth2 / OpenID Connect"]
26+
end
27+
28+
subgraph Storage["File Storage"]
29+
MinIO["MinIO (Object Storage)<br/>File storage<br/>PDF documents, images, etc.<br/>S3-compatible API"]
30+
end
31+
32+
subgraph Database["RDF Database"]
33+
GraphDB["GraphDB<br/>Triple store<br/>Ontologies and reference data<br/>SPARQL Endpoint"]
34+
end
35+
36+
subgraph Metadata["DDI Metadata"]
37+
Colectica["Colectica Repository API<br/>DDI Lifecycle Manager<br/>Statistical metadata"]
38+
end
39+
40+
Users -->|HTTPS| Frontend
41+
Frontend -->|REST API / HTTP| Backend
42+
Backend -->|OAuth2 / OIDC| Keycloak
43+
Backend -->|SPARQL / RDF| GraphDB
44+
Backend -->|S3 Protocol| MinIO
45+
Backend -->|REST API| Colectica
46+
47+
style Users fill:#e1f5ff
48+
style Frontend fill:#fff4e1
49+
style Backend fill:#e8f5e9
50+
style Keycloak fill:#fce4ec
51+
style MinIO fill:#f3e5f5
52+
style GraphDB fill:#e0f2f1
53+
style Colectica fill:#fff9c4
54+
```
55+
56+
## Main Components
57+
58+
### Frontend - Bauhaus
59+
60+
React single-page application (SPA) that provides the user interface for managing statistical metadata.
61+
62+
**Key Technologies:**
63+
- React 18 with Redux for state management
64+
- TypeScript for type safety
65+
- PrimeReact for UI components
66+
- Vite as bundler
67+
68+
[React Documentation](https://react.dev/) | [Redux Documentation](https://redux.js.org/)
69+
70+
### Backend - Spring Boot API
71+
72+
REST API that orchestrates all backend services and exposes business functionalities.
73+
74+
**Responsibilities:**
75+
- Orchestration of calls to different services
76+
- Business logic
77+
- Data validation and transformation
78+
- Security management
79+
80+
[Spring Boot Documentation](https://spring.io/projects/spring-boot)
81+
82+
### Security - Keycloak
83+
84+
Identity and Access Management (IAM) server that secures the entire stack.
85+
86+
**Features:**
87+
- Single Sign-On (SSO)
88+
- User and role management
89+
- OAuth2 and OpenID Connect protocols
90+
- Identity federation
91+
92+
[Keycloak Documentation](https://www.keycloak.org/documentation)
93+
94+
### File Storage - MinIO
95+
96+
S3-compatible object storage server for managing documents and files.
97+
98+
**Use Cases:**
99+
- PDF document storage
100+
- Images and graphics
101+
- Data files
102+
- Amazon S3-compatible API
103+
104+
[MinIO Documentation](https://min.io/docs/minio/linux/index.html)
105+
106+
### RDF Database - GraphDB
107+
108+
Triple store for storing and querying semantic data.
109+
110+
**Use Cases:**
111+
- Ontology storage
112+
- Metadata reference data
113+
- Semantic relationships
114+
- SPARQL queries
115+
116+
[GraphDB Documentation](https://graphdb.ontotext.com/documentation/)
117+
118+
### DDI Metadata - Colectica Repository
119+
120+
Statistical metadata manager based on the DDI (Data Documentation Initiative) standard.
121+
122+
**Features:**
123+
- Metadata lifecycle management
124+
- DDI Lifecycle standard support
125+
- Metadata versioning
126+
- REST API for programmatic access
127+
128+
[Colectica Documentation](https://www.colectica.com/) | [DDI Standard](https://ddialliance.org/)
129+
130+
## Data Flows
131+
132+
### Authentication
133+
134+
1. User accesses Bauhaus Frontend
135+
2. Redirect to Keycloak for authentication
136+
3. Keycloak validates credentials and issues a JWT token
137+
4. Frontend stores the token and sends it with each API request
138+
5. Spring Boot backend validates the token with Keycloak
139+
140+
### Metadata Retrieval
141+
142+
1. Frontend makes a REST request to the backend
143+
2. Backend queries:
144+
- **GraphDB** for reference data and classifications (via SPARQL)
145+
- **Colectica** for DDI metadata (via REST API)
146+
3. Backend aggregates and transforms the data
147+
4. JSON response returned to the frontend
148+
149+
### Document Management
150+
151+
1. Document upload from the frontend
152+
2. Backend validates and processes the file
153+
3. File storage in **MinIO** via S3 API
154+
4. Document metadata stored in GraphDB
155+
5. Reference returned to the frontend
156+
157+
158+
## Learn More
159+
160+
- [Getting Started](./getting-started) - Developer getting started guide
161+
- [Colectica Integration](./colectica) - Colectica Repository integration
162+
- [Bauhaus Back-Office](https://github.com/InseeFr/Bauhaus-Back-Office) - Backend GitHub repository

‎documentation/src/content/docs/guides/colectica.md‎

Lines changed: 170 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,176 @@ fr.insee.rmes.bauhaus.colectica.mock-server-enabled=false
6161
fr.insee.rmes.bauhaus.colectica.baseURI=https://colectica.production.example.com/api
6262
```
6363

64+
## API Communications
65+
66+
This section documents the API calls between Bauhaus and Colectica Repository for common operations.
67+
68+
### Physical Instance Operations
69+
70+
#### List All Physical Instances
71+
72+
Retrieving all physical instances from Bauhaus triggers a query to Colectica Repository.
73+
74+
**Bauhaus API Call:**
75+
```http
76+
GET {{API_BASE_URL}}/ddi/physical-instance
77+
```
78+
79+
**Colectica API Call:**
80+
```http
81+
POST {{COLECTICA_URL}}/api/v1/_query
82+
Content-Type: application/json
83+
```
84+
85+
**Request Body:**
86+
```json
87+
{
88+
"itemTypes": ["a51e85bb-6259-4488-8df2-f08cb43485f8"],
89+
"searchLatestVersion": true
90+
}
91+
```
92+
93+
**Notes:**
94+
- The `itemTypes` UUID `a51e85bb-6259-4488-8df2-f08cb43485f8` represents the Physical Instance type in DDI
95+
- `searchLatestVersion: true` ensures only the latest version of each item is returned
96+
97+
---
98+
99+
#### Get Specific Physical Instance
100+
101+
Retrieving a specific physical instance by agency and identifier.
102+
103+
**Bauhaus API Call:**
104+
```http
105+
GET {{API_BASE_URL}}/ddi/physical-instance/{agency}/{identifier}
106+
```
107+
108+
**Example:**
109+
```http
110+
GET {{API_BASE_URL}}/ddi/physical-instance/fr.inserm/00265728-02d5-478e-88db-55594a4bd260
111+
```
112+
113+
**Colectica API Call:**
114+
```http
115+
GET {{COLECTICA_URL}}/api/v1/ddiset/{agency}/{identifier}
116+
```
117+
118+
**Example:**
119+
```http
120+
GET {{COLECTICA_URL}}/api/v1/ddiset/fr.inserm/2514afe4-7b08-4500-be25-7a852a10fd8c
121+
```
122+
123+
**Notes:**
124+
- Colectica uses the DDI Set endpoint to retrieve complete metadata packages
125+
126+
---
127+
128+
#### Create or Update Physical Instance
129+
130+
Creating or updating a physical instance in Bauhaus persists the data to Colectica Repository.
131+
132+
**Bauhaus API Calls:**
133+
```http
134+
POST {{API_BASE_URL}}/ddi/physical-instance
135+
PUT {{API_BASE_URL}}/ddi/physical-instance
136+
```
137+
138+
**Colectica API Call:**
139+
```http
140+
POST {{COLECTICA_URL}}/api/v1/item
141+
Content-Type: application/json
142+
```
143+
144+
**Request Body Structure:**
145+
```json
146+
{
147+
"Items": [
148+
{
149+
"ItemType": "4bd6eef6-99df-40e6-9b11-5b8f64e5cb23",
150+
"AgencyId": "fr.insee",
151+
"Version": 2,
152+
"Identifier": "586a6306-c67d-4fda-a0ce-7e96564bda58",
153+
"Item": "<Fragment xmlns:r=\"ddi:reusable:3_3\" xmlns=\"ddi:instance:3_3\">...</Fragment>",
154+
"VersionDate": "2019-05-13T12:51:36.9134615Z",
155+
"VersionResponsibility": "acy5r8",
156+
"IsPublished": false,
157+
"IsDeprecated": false,
158+
"IsProvisional": false,
159+
"ItemFormat": "DC337820-AF3A-4C0B-82F9-CF02535CDE83"
160+
}
161+
],
162+
"options": {
163+
"namedOptions": [
164+
"RegisterOrReplace"
165+
]
166+
}
167+
}
168+
```
169+
170+
**Field Descriptions:**
171+
172+
| Field | Type | Description |
173+
|-------|------|-------------|
174+
| `ItemType` | UUID | DDI item type identifier (e.g., Group, StudyUnit, PhysicalInstance) |
175+
| `AgencyId` | String | Agency identifier (e.g., `fr.insee`) |
176+
| `Version` | Integer | Version number of the metadata item |
177+
| `Identifier` | UUID | Unique identifier for the item |
178+
| `Item` | XML String | DDI-compliant XML fragment containing the metadata |
179+
| `VersionDate` | ISO DateTime | Timestamp of this version |
180+
| `VersionResponsibility` | String | User ID responsible for this version |
181+
| `IsPublished` | Boolean | Publication status |
182+
| `IsDeprecated` | Boolean | Deprecation flag |
183+
| `IsProvisional` | Boolean | Provisional status |
184+
| `ItemFormat` | UUID | Format identifier for the XML content |
185+
186+
**Options:**
187+
- `RegisterOrReplace`: If the item already exists, it will be replaced; otherwise, it will be created
188+
189+
**Example XML Fragment:**
190+
```xml
191+
<Fragment xmlns:r="ddi:reusable:3_3" xmlns="ddi:instance:3_3">
192+
<Group isUniversallyUnique="true" versionDate="2019-05-13T12:51:36.9134615Z" xmlns="ddi:group:3_3">
193+
<r:URN>urn:ddi:fr.insee:586a6306-c67d-4fda-a0ce-7e96564bda58:1</r:URN>
194+
<r:Agency>fr.insee</r:Agency>
195+
<r:ID>586a6306-c67d-4fda-a0ce-7e96564bda58</r:ID>
196+
<r:Version>1</r:Version>
197+
<r:UserID typeOfUserID="colectica:sourceId">INSEE-BDF-SGRP</r:UserID>
198+
<r:Citation>
199+
<r:Title>
200+
<r:String xml:lang="en-IE">Household budget survey</r:String>
201+
<r:String xml:lang="fr-FR">Enquête Budget de famille</r:String>
202+
</r:Title>
203+
<r:AlternateTitle>
204+
<r:String xml:lang="en-IE">BDF</r:String>
205+
<r:String xml:lang="fr-FR">BDF</r:String>
206+
</r:AlternateTitle>
207+
</r:Citation>
208+
<r:StudyUnitReference>
209+
<r:Agency>fr.insee</r:Agency>
210+
<r:ID>62a0a1ec-0fc3-4aaf-bc55-e26fd80347c9</r:ID>
211+
<r:Version>1</r:Version>
212+
<r:TypeOfObject>StudyUnit</r:TypeOfObject>
213+
</r:StudyUnitReference>
214+
</Group>
215+
</Fragment>
216+
```
217+
218+
---
219+
220+
### DDI Item Types
221+
222+
Common DDI item type UUIDs used in Colectica API calls:
223+
224+
| Item Type | UUID |
225+
|-----------|------|
226+
| Physical Instance | `a51e85bb-6259-4488-8df2-f08cb43485f8` |
227+
| Group | `4bd6eef6-99df-40e6-9b11-5b8f64e5cb23` |
228+
| Study Unit | (varies by implementation) |
229+
230+
64231
## Additional Resources
65232

66233
- [DDI Alliance](https://ddialliance.org/) - Official DDI standards documentation
67-
- [Colectica Documentation](https://www.colectica.com/documentation) - Colectica-specific guides
234+
- [Colectica Documentation](https://www.colectica.com/documentation) - Colectica-specific guides
235+
- [DDI Lifecycle 3.3 Specification](https://ddialliance.org/Specification/DDI-Lifecycle/3.3/) - Technical specification for DDI XML structure
236+
- [Colectica REST API](https://www.colectica.com/) - Colectica API documentation

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "bauhaus",
3-
"version": "4.15.0",
3+
"version": "4.16.0",
44
"type": "module",
55
"description": "Web application for the management of concepts, classifications and other statistical objects",
66
"repository": {

0 commit comments

Comments
 (0)