# platform-os/docskit-landing architecture

> Architecture diagram of the GitHub repository platform-os/docskit-landing, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/platform-os/docskit-landing
- Repository: https://github.com/platform-os/docskit-landing

## Overview

##### Project Type and Purpose
- This is a monorepo containing two primary concerns:
a) A Jamstack‐style documentation site built with Gatsby (React + MDX).
b) A set of platformOS “modules” (Liquid templates, GraphQL endpoints, commands) that extend the platformOS backend for various features (contact forms, courses, user management, theming, permissions, etc.).
- README confirms it’s the “platformOS DocsKit product documentation site,” so the primary outward‐facing system is a static docs site, backed by a suite of platformOS modules for dynamic features.

##### File Structure Analysis
- Top‐level directories:
- src/: Gatsby site code (pages, components, MDX docs, plugins)
- modules/: platformOS module packages (admin, contact, courses, core, permission, theme-manager, user)
- app/: configuration (app/config.yml, i18n files)
- .github/workflows/: CI/CD definitions (preview, deploy_to_qa, deploy_to_production)
- Each module has a “public” side (Liquid view templates, public GraphQL, commands, assets) and a “private” side (server-only APIs, model schemas, emails, translations).
- CI/CD: on pull requests, a preview deploy; on merges/tags, QA and production deploys to platformOS environments.

##### Key Architectural Patterns & Technologies
- Jamstack (Gatsby + MDX + React) for static documentation.
- Plugin architecture: Gatsby plugins (under src/plugins and src/src/@platformos/…-theme) and platformOS modules.
- Monorepo with package.json at root and per-module package.json for the “courses” module and Gatsby site.
- Liquid templating & GraphQL on the platformOS backend modules.
- CI/CD pipelines via GitHub Actions, deploying both the static site and the modules to platformOS environments.

##### Main Components
a. Developer Workstation (writes MDX, JS, Liquid, YAML, commits to GitHub)
b. GitHub Repository (monorepo)
c. CI/CD (GitHub Actions workflows):
- preview.yml -> Preview environment
- deploy_to_qa.yml -> QA environment
- deploy_to_production.yml -> Production environment
d. Build Processes:
- Gatsby Build (static site generator)
- Module Packaging (platformOS module CLI/package tool)
e. Hosting/Runtime Environments on platformOS:
- Static hosting/CDN for the documentation site
- platformOS application server(s) running module code (Liquid, GraphQL endpoints, commands)
f. External Services:
- CDN (e.g., CloudFront, Netlify)
- Analytics (plausible.js)
- Email/SMS providers used by modules (contacts, courses notifications)

##### Relationships & Interactions
- The static site consumes GraphQL data from modules (if any dynamic preview) or can link to live APIs (contact form).
- Modules expose endpoints (REST or GraphQL) that are invoked by the static site or by user actions (submissions, admin dashboards).

##### Architectural Highlights
- Monorepo ensures modules and site share configuration, code style (ESLint, Prettier), and CI pipelines.
- Clear separation: Frontend (React + MDX) vs. Backend modules (Liquid + GraphQL).
- Plugin/theme layering: Gatsby theme (“@platformos/gatsby-theme-platformos-docskit”) sits between raw MDX content and the final site.
- Module layering: private logic (model schemas, server-side commands) vs. public logic (views, GraphQL, assets).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Workstation"
        Dev["Developer Workstation"]:::dev
    end

    Dev -->|"Commit Code"| GitHub["GitHub Repo (monorepo)"]:::repo

    subgraph "CI/CD Pipeline"
        GH_Actions["GitHub Actions"]:::cicd
        preview["preview.yml"]:::cicd
        qa["deploy_to_qa.yml"]:::cicd
        prod["deploy_to_production.yml"]:::cicd
    end

    GitHub --> GH_Actions
    GH_Actions --> preview
    GH_Actions --> qa
    GH_Actions --> prod

    subgraph "Build Processes"
        GatsbyBuild["Gatsby Build"]:::static
        ModuleBuild["Module Packaging"]:::backend
    end

    preview --> GatsbyBuild
    qa --> GatsbyBuild
    prod --> GatsbyBuild

    preview --> ModuleBuild
    qa --> ModuleBuild
    prod --> ModuleBuild

    GatsbyBuild --> CDN["CDN / Static Hosting"]:::external
    ModuleBuild --> PlatformOS["platformOS Server"]:::external

    subgraph "Runtime Interactions"
        EndUser["End User"]:::user
        CDN -->|"HTTP GET"| EndUser
        EndUser -->|"Form submit / API"| PlatformOS
        PlatformOS --> DB["platformOS Database"]:::database
        PlatformOS --> External["External Services"]:::external
    end

    subgraph "Frontend: Gatsby Site"
        MDX["MDX Documentation Content"]:::static
        Theme["Gatsby Theme Layer"]:::static
        Plugins["Gatsby Plugins"]:::static
        ReactComp["React Components & Pages"]:::static
        Config["Gatsby Config & Entry Points"]:::static
    end

    subgraph "PlatformOS Modules"
        subgraph "Contact Module"
            ContactPub["modules/contact/public"]:::module
            ContactPriv["modules/contact/private"]:::module
        end
        subgraph "Courses Module"
            CoursesPub["modules/courses/public"]:::module
            CoursesPriv["modules/courses/private"]:::module
        end
        subgraph "Other Modules"
            Admin["modules/admin"]:::module
            Core["modules/core"]:::module
            Permission["modules/permission"]:::module
            ThemeMgr["modules/theme-manager"]:::module
            UserMod["modules/user"]:::module
        end
    end

    subgraph "App Config & Localization"
        ConfigYML["app/config.yml"]:::config
        Trans["app/translations/"]:::config
    end

    GitHub --> GatsbyBuild
    GitHub --> ModuleBuild

    GatsbyBuild --> MDX
    GatsbyBuild --> Theme
    GatsbyBuild --> Plugins
    GatsbyBuild --> ReactComp
    GatsbyBuild --> Config

    ModuleBuild --> ContactPub
    ModuleBuild --> ContactPriv
    ModuleBuild --> CoursesPub
    ModuleBuild --> CoursesPriv
    ModuleBuild --> Admin
    ModuleBuild --> Core
    ModuleBuild --> Permission
    ModuleBuild --> ThemeMgr
    ModuleBuild --> UserMod

    classDef dev fill:#f9f,stroke:#333,stroke-width:1px;
    classDef repo fill:#fff,stroke:#333,stroke-width:1px;
    classDef cicd fill:#f90,stroke:#333,stroke-width:1px;
    classDef static fill:#bbf,stroke:#333,stroke-width:1px;
    classDef backend fill:#bfb,stroke:#333,stroke-width:1px;
    classDef module fill:#afa,stroke:#333,stroke-width:1px;
    classDef external fill:#ccc,stroke:#333,stroke-width:1px;
    classDef database fill:#999,stroke:#333,stroke-width:1px;
    classDef user fill:#eee,stroke:#333,stroke-width:1px;
    classDef config fill:#ddd,stroke:#333,stroke-width:1px;

    click MDX "https://github.com/platform-os/docskit-landing/tree/master/src/docs/"
    click GatsbyBuild "https://github.com/platform-os/docskit-landing/tree/master/src/"
    click Config "https://github.com/platform-os/docskit-landing/blob/master/src/gatsby-config.js"
    click Config "https://github.com/platform-os/docskit-landing/blob/master/src/gatsby-browser.js"
    click Config "https://github.com/platform-os/docskit-landing/blob/master/src/gatsby-ssr.js"
    click Config "https://github.com/platform-os/docskit-landing/blob/master/src/index.js"
    click Plugins "https://github.com/platform-os/docskit-landing/tree/master/src/plugins/docskit-sitemap/"
    click Theme "https://github.com/platform-os/docskit-landing/tree/master/src/src/@platformos/gatsby-theme-platformos-docskit/"
    click ReactComp "https://github.com/platform-os/docskit-landing/tree/master/src/src/components/"
    click ReactComp "https://github.com/platform-os/docskit-landing/tree/master/src/src/pages/"
    click ConfigYML "https://github.com/platform-os/docskit-landing/blob/master/app/config.yml"
    click Trans "https://github.com/platform-os/docskit-landing/tree/master/app/translations/"
    click preview "https://github.com/platform-os/docskit-landing/blob/master/.github/workflows/preview.yml"
    click qa "https://github.com/platform-os/docskit-landing/blob/master/.github/workflows/deploy_to_qa.yml"
    click prod "https://github.com/platform-os/docskit-landing/blob/master/.github/workflows/deploy_to_production.yml"
    click ContactPub "https://github.com/platform-os/docskit-landing/tree/master/modules/contact/public/views/"
    click ContactPriv "https://github.com/platform-os/docskit-landing/tree/master/modules/contact/public/lib/commands/contact/"
    click CoursesPub "https://github.com/platform-os/docskit-landing/tree/master/modules/courses/public/"
    click CoursesPriv "https://github.com/platform-os/docskit-landing/tree/master/modules/courses/private/"
    click Admin "https://github.com/platform-os/docskit-landing/tree/master/modules/admin/"
    click Core "https://github.com/platform-os/docskit-landing/tree/master/modules/core/"
    click Permission "https://github.com/platform-os/docskit-landing/tree/master/modules/permission/"
    click ThemeMgr "https://github.com/platform-os/docskit-landing/tree/master/modules/theme-manager/"
    click UserMod "https://github.com/platform-os/docskit-landing/tree/master/modules/user/"
```
