How platform-os/docskit-landing works
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).