# tewhatuora/api-standards architecture

> Architecture diagram of the GitHub repository tewhatuora/api-standards, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tewhatuora/api-standards
- Repository: https://github.com/tewhatuora/api-standards

## Overview

##### Main Components
- Content Repository: This includes the raw Markdown files in the “docs” and “versioned_docs” directories, along with the supporting documents in the “dictionaries” folder and additional documentation (e.g., glossary, community, and API security/development sections).
- React Components & Frontend: Under the “src” folder, components like ApiStandard.jsx, ApiStandardsChecklist.jsx, AsyncApiViewer.jsx, and DetailedDescription.jsx form the UI presentation layer. The styling (CSS in src/css) and theme (src/theme) files help craft the look and feel.
- Build System & Static Site Generator: Docusaurus is used (indicated by docusaurus.config.js and sidebars.js) to compile the Markdown content and React components into a static website. Babel is also present for JavaScript transpilation (babel.config.js).
- Utility and Build Scripts: The /scripts/extractStandards.js script automatically parses React components to generate the master checklist and tooltips. There are also npm scripts for spell checking and markdown linting.
- Deployment Pipeline: GitHub Actions workflows (e.g., .github/workflows/deploy-gh-pages.yml) show that automated deployment to GitHub Pages is used to publish the site.
- Versioning Infrastructure: With directories like versioned_docs and versioned_sidebars, the project supports versioned documentation.

##### Relationships and Interactions
- Content Creation: Editors update Markdown files in “docs” (and versioned_docs for historical releases) which serve as the content source.
- Rendering Pipeline: The static site generator (Docusaurus) ingests the Markdown content and integrates it with React components from the “src” directory. The build process uses Node.js (npm install, npm start) to create the final static site.
- Component Enhancement: The <ApiStandard> component encapsulates standards rules and gets processed during build (via extraction scripts) to generate interactive tooltips and checklist elements.
- Quality & Consistency: Spell check and markdown lint npm scripts ensure that content follows defined standards.
- Deployment: Once the site is built, GitHub Actions deploys the output (likely to the gh-pages branch) for public access at https://apistandards.digital.health.nz.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project separates content (Markdown docs), business logic (React components), and deployment (build scripts and CI/CD in GitHub Actions).
- Static Site Generation: This pattern is used to produce a highly performant, easy-to-host documentation website.
- Versioning and Standardization: The versioned_docs structure demonstrates careful consideration for documentation evolution and backward compatibility.
- Extensibility through Components: Custom React components (e.g., <ApiStandard>) enable dynamic features across static content while maintaining consistency.

##### Relevant Technologies and Frameworks
- Docusaurus as the static site generator.
- React for frontend components.
- Node.js and npm for development, building, and running scripts.
- GitHub Actions for CI/CD and automated deployment.
- Babel for JavaScript transpilation.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Content Layer"
        A["Docs"]
        B["Versioned Docs"]
        C["Dictionaries"]
    end

    subgraph "Frontend Layer"
        D["ApiStandard.jsx"]
        E["ApiStandardsChecklist.jsx"]
        F["AsyncApiViewer.jsx"]
        G["DetailedDescription.jsx"]
        H["Styling (custom.css)"]
        I["Theme (MDXComponents.js)"]
    end

    subgraph "Build/Processing Layer"
        J["Docusaurus Config (docusaurus.config.js)"]
        K["Sidebars (sidebars.js)"]
        L["Babel Transpilation (babel.config.js)"]
        M["Standards Extraction (extractStandards.js)"]
    end

    subgraph "CI/CD & Deployment"
        N["GitHub Actions Workflow (deploy-gh-pages.yml)"]
        O["Deployment (GitHub Pages)"]
    end

    A --> J
    B --> J
    C --> J
    D --> J
    E --> J
    F --> J
    G --> J
    H --> J
    I --> J

    J --> N
    K --> N
    L --> N
    M --> N

    N --> O

    classDef content fill:#F9D7A1,stroke:#333,stroke-width:2px;
    classDef frontend fill:#A1CBE9,stroke:#333,stroke-width:2px;
    classDef build fill:#B7E4C7,stroke:#333,stroke-width:2px;
    classDef cicd fill:#D4A5A5,stroke:#333,stroke-width:2px;
    classDef deploy fill:#E2B0FF,stroke:#333,stroke-width:2px;

    class A,B,C content;
    class D,E,F,G,H,I frontend;
    class J,K,L,M build;
    class N cicd;
    class O deploy;

    click A "https://github.com/tewhatuora/api-standards/tree/main/docs"
    click B "https://github.com/tewhatuora/api-standards/tree/main/versioned_docs"
    click C "https://github.com/tewhatuora/api-standards/tree/main/dictionaries"
    click D "https://github.com/tewhatuora/api-standards/blob/main/src/components/ApiStandard.jsx"
    click E "https://github.com/tewhatuora/api-standards/blob/main/src/components/ApiStandardsChecklist.jsx"
    click F "https://github.com/tewhatuora/api-standards/blob/main/src/components/AsyncApiViewer.jsx"
    click G "https://github.com/tewhatuora/api-standards/blob/main/src/components/DetailedDescription.jsx"
    click H "https://github.com/tewhatuora/api-standards/tree/main/src/css"
    click I "https://github.com/tewhatuora/api-standards/blob/main/src/theme/MDXComponents.js"
    click J "https://github.com/tewhatuora/api-standards/blob/main/docusaurus.config.js"
    click K "https://github.com/tewhatuora/api-standards/blob/main/sidebars.js"
    click L "https://github.com/tewhatuora/api-standards/blob/main/babel.config.js"
    click M "https://github.com/tewhatuora/api-standards/blob/main/scripts/extractStandards.js"
    click N "https://github.com/tewhatuora/api-standards/blob/main/.github/workflows/deploy-gh-pages.yml"
```
