How ministero-salute/it-fse-support works
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