Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
193 lines (150 loc) · 5.47 KB

ARCHITECTURE.md

File metadata and controls

193 lines (150 loc) · 5.47 KB
Raw

YGIT Public Documentation Architecture

Version: 1.0
Status: Ready to Use
Repository: vibtools/ygit-platform
Default public domain: ygit.dev
Framework: Docusaurus 3.10.2

1. Purpose

This repository is the complete public-information layer for YGIT. It is not a copy of the private platform codebase and it is not an internal engineering archive.

It has four responsibilities:

  1. Explain YGIT to users and search engines.
  2. Provide complete user guidance.
  3. Publish stable CLI, SDK, and API contracts.
  4. Build a static documentation website deployable to Cloudflare Pages or any static host.

2. Content architecture

YGIT Public Documentation Platform
├── Product landing pages
├── User documentation
├── CLI documentation
├── SDK documentation
├── API documentation
└── Public updates and release notes

Each documentation family uses an independent Docusaurus docs plugin instance.

Surface Source Public route Sidebar Version lifecycle
User Docs docs/ /docs/ sidebars.ts Product/user documentation
CLI cli/ /cli/ sidebars.cli.ts CLI releases
SDK sdk/ /sdk/ sidebars.sdk.ts SDK package releases
API api/ /api/ sidebars.api.ts Public API contract
Updates updates/ /updates/ Blog index Announcements and changelog

This prevents unrelated version histories from becoming coupled. A CLI release does not require versioning the user guide, and an SDK release does not require a second documentation site.

3. Repository structure

ygit-platform/
├── .github/
│   ├── workflows/ci.yml
│   ├── ISSUE_TEMPLATE/
│   └── PULL_REQUEST_TEMPLATE.md
├── api/
├── cli/
├── docs/
├── sdk/
├── updates/
├── scripts/
│   └── validate-public-content.mjs
├── src/
│   ├── css/custom.css
│   └── pages/
├── static/
│   ├── img/
│   ├── _headers
│   └── robots.txt
├── docusaurus.config.ts
├── sidebars.ts
├── sidebars.cli.ts
├── sidebars.sdk.ts
├── sidebars.api.ts
├── CONTENT_POLICY.md
├── CONTRIBUTING.md
├── DEPLOYMENT.md
└── README.md

4. Product-boundary rule

YGIT remains a deployment automation platform. Public documentation must not redefine it as a website builder, hosting company, CMS, or general-purpose control panel.

The public flow is:

Import Repository
→ Analyze Repository
→ Connect Accounts
→ Review Configuration
→ Deploy
→ Website Live

Public documentation should reinforce user ownership of the repository, Cloudflare account, domain, code, and infrastructure.

5. Content lifecycle

Internal product evidence
→ Public-content rewrite
→ Technical verification
→ Security/privacy review
→ SEO and accessibility review
→ Pull request
→ CI validation
→ Preview deployment
→ Merge
→ Production deployment

Internal documents are inputs, not publishable artifacts. They must be rewritten for the intended audience.

6. Future feature expansion

A new public feature normally requires only content changes:

docs/<feature>/
├── _category_.json
├── overview.md
├── setup.md
├── usage.md
├── limitations.md
└── troubleshooting.md

A new framework plugin or top-level documentation surface is justified only when the feature has an independent release/version lifecycle comparable to CLI, SDK, or API.

7. Versioning policy

Do not version documentation prematurely. Docusaurus version snapshots increase maintenance and build cost. Enable versioning when a stable public contract must remain available after breaking changes.

npm run version:docs -- 1.0.0
npm run version:cli -- 1.0.0
npm run version:sdk -- 1.0.0
npm run version:api -- 1.0.0

Version only the affected surface.

8. SEO architecture

  • One canonical domain through SITE_URL
  • Human-readable routes
  • Unique title and description front matter on every content page
  • Automatic sitemap generation from the classic preset
  • robots.txt and social-preview image
  • SoftwareApplication structured data
  • Semantic headings and descriptive link text
  • Separate landing pages for user, CLI, SDK, and API search intent
  • Public updates feed for fresh crawlable content

See SEO_GUIDE.md.

9. Security boundary

The public-content validator blocks common credential values, private key material, exact internal commit hashes, and references to the private platform repository. CI must run it before every production build.

The validator complements review; it does not replace it. Screenshots, diagrams, logs, and copied examples require manual privacy review.

10. Deployment architecture

Docusaurus emits static files to build/. The repository has no hosting-provider business logic.

GitHub commit
→ CI validation
→ Docusaurus build
→ build/
→ Cloudflare Pages or another static host

For Cloudflare Pages:

Build command: npm run build
Output directory: build
Production branch: main
Node.js: 22

11. Architecture gate

A structural change requires documentation when it changes one of these:

  • Public route families
  • Documentation plugin instances
  • Versioning strategy
  • Search provider
  • Content security policy
  • Deployment output contract
  • Localization architecture

Normal documentation additions do not require an architecture revision.