# ministero-salute/it-fse-support architecture

> Architecture diagram of the GitHub repository ministero-salute/it-fse-support, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ministero-salute/it-fse-support
- Repository: https://github.com/ministero-salute/it-fse-support

## Overview

##### Project Type and Purpose
- This repository is primarily a **static documentation site** (“Supporto FSE 2.0”) that provides integration guides, sample artifacts (CDA XML, X.509 certs), OpenAPI specifications, and FAQs for developers integrating with the Fascicolo Sanitario Elettronico (FSE) Gateway (GTW).
- It uses the **Astro** static-site generator (under `doc/wiki`) and leverages **Pagefind** for client-side search, then publishes the output under the top-level `docs/` folder for GitHub Pages hosting.

##### High-Level File Structure Analysis
- `doc/`
- Sub-directories for accreditation, gateway integration, middleware, provisioning, telemedicine, examples, FAQs, etc.
- Contains reference PEM certs, sample CDA files, OpenAPI YAML (`openapi.yaml`), and markdown docs.
- `openapi/`
- Gateway OpenAPI definitions (`swagger_gtw.yaml`).
- `validazione/`
- Schematron/XSD pointers for CDA validation.
- `doc/wiki/`
- Astro project: `package.json`, `astro.config.mjs`, `src/content` (MDX & Markdown), `public`, `tsconfig.json`.
- `docs/`
- Generated static site (HTML/CSS/JS) including Pagefind search index and assets.

##### Key README Insights
- The README explains the scope (gateway entry-point, validation, mock publishing), quickstart links, certificate request procedure, and pointers to external tools and repositories (JWT token generator, GTW test container, catalogs).
- No backend code—this is documentation only. The external GTW service, token-gen tools, and test containers live in other repos.

##### Main Components
a. **Content Sources (Inputs)**
- `doc/` folder (integration guides, examples, schemas)
- `openapi/` folder (API definitions)
- `doc/wiki/src/content` (site copy in MDX/Markdown)
b. **Static Site Generator**
- Astro build process (Node.js scripts invoked by `npm run build`)
- Pagefind indexing step (builds WASM search index)
c. **Output / Hosting**
- Generated site under top-level `docs/`
- Hosted on GitHub Pages (or equivalent static host)
d. **Client-Side Components**
- HTML/CSS/JS pages
- Pagefind WASM module for on-page search
e. **External Services & Artifacts**
- FSE GTW Test & Production endpoints (for validation, publishing)
- Certificate Authority (Sogei CA in `doc/CA_Sogei`)
- JWT token generation tools (external repo)
- Provisioning API (external service defined by `openapi/provisioning/openapi.yaml`)

##### Relationships and Data Flows
- **Content → SSG**: Raw markdown/MDX and OpenAPI → Astro → static HTML, CSS, JS.
- **SSG → Hosting**: Build output (`docs/`) → GitHub Pages.
- **User Browsers → Hosted Site**: Users load docs, search via Pagefind WASM → static assets.
- **Certificate Process**: Guides show flows for CSR submission to CA and usage with GTW endpoints.

##### Architectural Patterns & Design Principles
- **Static Site Generation (SSG)**: decouples content management from runtime hosting.
- **Content-First Organization**: clear separation of raw documentation (`doc/` & `wiki/src`) and generated output (`docs/`).
- **Client-Side Search**: pre-built index via Pagefind (WASM) for offline search capability.
- **API-Driven Docs**: OpenAPI specs embedded for provisioning and gateway integration.

##### Technologies, Frameworks, and Libraries
- Astro (SSG)
- Node.js / npm
- Pagefind (WASM search engine)
- GitHub Pages (hosting)
- OpenAPI / Swagger
- X.509 certificates (PEM, CSR with OpenSSL/keytool)
- XML CDA, XSD, Schematron for validation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Content & Build (blue)
    subgraph "Content Sources"
        direction TB
        IntegrationGuides["Integration Guides"]:::content
        AccreditationGuides["Accreditation Guides"]:::content
        MiddlewareDocs["Middleware Regional Docs"]:::content
        ProvisioningGuide["Provisioning API Guide"]:::content
        CDAExamples["CDA Examples"]:::content
        FAQs["FAQs"]:::content
        TelemedicineDocs["Telemedicine Docs"]:::content
        TransitionalDocs["Transitional Docs"]:::content
        DistributedScripts["Distributed Scripts & Zips"]:::content
        MetadataMapping["Metadata Mapping"]:::content
        CentralizedTests["Centralized Test Artifacts"]:::content
        CA_PEMs["Certificate Authority PEMs"]:::content
        ValidationSchemas["Validation Schemas"]:::content
        GatewayOpenAPI["Gateway OpenAPI Definitions"]:::content
        ProvisioningOpenAPI["Provisioning OpenAPI Definitions"]:::content
        SiteCopy["Site Copy (MDX/Markdown)"]:::content
    end

    subgraph "Static Site Generation" 
        direction TB
        AstroConfig["Astro Config & Tooling\n(npm run build)"]:::build
        AstroSource["Astro Source Code & Content"]:::build
        PagefindOutput["Pagefind Search Index"]:::build
    end

    %% Hosting & Delivery (green)
    subgraph "Output & Hosting"
        direction TB
        GeneratedSite["Generated Static Site\n(docs/)"]:::hosting
        GitHubPages["GitHub Pages"]:::hosting
        EndUsers["End Users\n(Browsers)"]:::hosting
    end

    %% External Services (orange)
    subgraph "External Services"
        direction TB
        FSE_GTW["FSE GTW Endpoints"]:::external
        Sogei_CA["Sogei Certificate Authority"]:::external
        JWT_Tools["JWT Token Generation Tools"]:::external
        ProvisioningAPI["Provisioning API Service"]:::external
    end

    %% Connections
    IntegrationGuides -->|inputs| AstroConfig
    AccreditationGuides --> AstroConfig
    MiddlewareDocs --> AstroConfig
    ProvisioningGuide --> AstroConfig
    CDAExamples --> AstroConfig
    FAQs --> AstroConfig
    TelemedicineDocs --> AstroConfig
    TransitionalDocs --> AstroConfig
    DistributedScripts --> AstroConfig
    MetadataMapping --> AstroConfig
    CentralizedTests --> AstroConfig
    CA_PEMs --> AstroConfig
    ValidationSchemas --> AstroConfig
    GatewayOpenAPI --> AstroConfig
    ProvisioningOpenAPI --> AstroConfig
    SiteCopy --> AstroSource

    AstroConfig -->|build| GeneratedSite
    AstroSource --> GeneratedSite
    AstroConfig --> PagefindOutput
    PagefindOutput --> GeneratedSite

    GeneratedSite -->|deploy| GitHubPages
    GitHubPages -->|serve| EndUsers
    EndUsers -->|search via Pagefind WASM| PagefindOutput

    EndUsers -->|consume API docs| FSE_GTW
    EndUsers -->|generate tokens| JWT_Tools
    EndUsers -->|interact provisioning| ProvisioningAPI
    EndUsers -->|submit CSR| Sogei_CA

    %% Click Events
    click IntegrationGuides "https://github.com/ministero-salute/it-fse-support/blob/main/doc/integrazione-gateway/README.md"
    click AccreditationGuides "https://github.com/ministero-salute/it-fse-support/blob/main/doc/accreditamento/README.md"
    click MiddlewareDocs "https://github.com/ministero-salute/it-fse-support/blob/main/doc/middleware-regionale/README.md"
    click ProvisioningGuide "https://github.com/ministero-salute/it-fse-support/blob/main/doc/provisioning/README.md"
    click ProvisioningGuide "https://github.com/ministero-salute/it-fse-support/blob/main/doc/provisioning/openapi.yaml"
    click CDAExamples "https://github.com/ministero-salute/it-fse-support/blob/main/doc/esempi/CDA/README.md"
    click FAQs "https://github.com/ministero-salute/it-fse-support/blob/main/doc/faq/README.md"
    click TelemedicineDocs "https://github.com/ministero-salute/it-fse-support/blob/main/doc/telemedicina/README.md"
    click TransitionalDocs "https://github.com/ministero-salute/it-fse-support/blob/main/doc/transitorio/README.md"
    click DistributedScripts "https://github.com/ministero-salute/it-fse-support/blob/main/doc/distribuito/FSEDistribuito.zip"
    click MetadataMapping "https://github.com/ministero-salute/it-fse-support/blob/main/doc/mapping-metadati/README.md"
    click CentralizedTests "https://github.com/ministero-salute/it-fse-support/tree/main/doc/test-centralizzati/"
    click CA_PEMs "https://github.com/ministero-salute/it-fse-support/tree/main/doc/CA_Sogei/PRODUZIONE/"
    click CA_PEMs "https://github.com/ministero-salute/it-fse-support/tree/main/doc/CA_Sogei/VALIDAZIONE/"
    click ValidationSchemas "https://github.com/ministero-salute/it-fse-support/blob/main/validazione/README.md"
    click GatewayOpenAPI "https://github.com/ministero-salute/it-fse-support/blob/main/openapi/gateway/swagger_gtw.yaml"
    click ProvisioningOpenAPI "https://github.com/ministero-salute/it-fse-support/blob/main/openapi/provisioning/openapi.yaml"
    click SiteCopy "https://github.com/ministero-salute/it-fse-support/tree/main/doc/wiki/src/content/"
    click AstroConfig "https://github.com/ministero-salute/it-fse-support/blob/main/doc/wiki/astro.config.mjs"
    click AstroConfig "https://github.com/ministero-salute/it-fse-support/blob/main/doc/wiki/package.json"
    click AstroConfig "https://github.com/ministero-salute/it-fse-support/blob/main/doc/wiki/tsconfig.json"
    click AstroSource "https://github.com/ministero-salute/it-fse-support/tree/main/doc/wiki/src/"
    click PagefindOutput "https://github.com/ministero-salute/it-fse-support/tree/main/docs/pagefind/"

    click GeneratedSite "https://github.com/ministero-salute/it-fse-support/blob/main/docs/index.html"

    %% Styles
    classDef content fill:#D0E8FF,stroke:#165EAB,color:#000;
    classDef build fill:#B3FFC9,stroke:#0A8E00,color:#000;
    classDef hosting fill:#DFFCCB,stroke:#3E8E00,color:#000;
    classDef external fill:#FFE6B3,stroke:#C76A00,color:#000;
```
