System Architecture

SCS is a local-first, terminal-first system. It owns the content state and the work products; WordPress is the review and publishing surface.

Location

/home/rezriz/github/server-side-program/scs

Documentation lives in brain-donnyaw-cf-pages/seo-content-systems (SCS section).

Components

Component	Responsibility
config/sites.csv	Site registry, WP root, SSH host, WP user, PID prefix
scs import-csv	Normalise raw exports into keywords.csv
scs score	Compute n_sv, n_kd, gos, gos_tier (supporting)
scs research	Create/check research/<pid>/
scs brief	Render/check/approve the Markdown brief
scs sync	Validate, allocate PIDs, create stage rows, render front matter
scs publish	Create/update a WordPress draft, map ACF/taxonomy
scs qa	Pull/check the WordPress review gate
scs check	Enforce schemas, references, statuses, research, brief, QA
VisiData / nvim / Yazi	Explore CSV, edit Markdown, browse files

Repository layout

scs/
├── config/
│   ├── sites.csv
│   └── pids.reserved
├── data/
│   └── <workspace>/
│       ├── <workspace>-keywords.csv
│       ├── <workspace>-clusters.csv
│       ├── <workspace>-briefs.csv
│       ├── <workspace>-links.csv
│       ├── <workspace>-publishing.csv
│       ├── <workspace>-performance.csv
│       ├── md/<pid>--*.md      # brief + article, one file
│       ├── research/<pid>/
│       ├── assets/
│       └── staging/
├── raw/                      # optional: raw exports, created on demand
├── scripts/
│   ├── scs.py
│   ├── scs_core.py
│   ├── scs_research.py
│   ├── scs_brief.py
│   ├── scs_wp.py
│   └── test_*.py
└── integrations/
    ├── visidata/scs_pid.py
    └── wordpress/wpstrategist-review-gate/

Data flow

1. Gather raw exports into raw/ or staging/.
2. Import into the workspace keyword CSV.
3. Score GOS as a supporting metric.
4. Research in research/<pid>/.
5. Decide (go / hold / no) and plan the cluster.
6. Brief in Markdown and approve.
7. Draft in the article Markdown, after the article marker.
8. Create/update a draft with SCS; use the site's approved WordPress workflow for pending, scheduled, or published state, then read status back with SCS.
9. Review the rendered post in WordPress/ACF.
10. Pull QA, then advance or publish from the terminal.
11. Measure GSC and refresh.

Front matter contract

For the canonical reference and the brief/article markers, see Front Matter.

Article Markdown begins with compact writer-focused YAML front matter and keeps the authored brief/article body below it. Public CMS fields are top-level; SCS context lives under scs.identity, scs.writing, scs.links, scs.editorial, and scs.research.

---
# Public CMS fields
title: "VPS vs Dedicated Server"
description: null
category: "Hosting"
tags:
  - "VPS"
  - "dedicated server"
content_type: "comparison"
status: "Draft"
date: null
slug: "vps-vs-dedicated-server"

scs:
  schema: scs-content/v3
  identity:
    pid: "OPS-0001"
    site_id: "opshell"
  writing:
    audience: "Small businesses"
    intent: "Commercial investigation"
    primary_keyword: "vps vs dedicated server"
    supporting_keywords: []
    angle: "Compare practical trade-offs"
    differentiation: "Decision-focused comparison"
    target_words: 1800
    tone: "Clear and practical"
    author_role: "Practitioner"
    entities_to_cover:
      - "virtual private server"
      - "dedicated server"
    questions_to_answer: []
  links:
    internal: []
  editorial:
    reviewer: null
    review_due: null
    disclosure: null
  research:
    path: "data/pilot/research/OPS-0001/"
    status: "needs_review"
---

Top-level description and slug are sourced from publishing.csv (meta_description and slug). The title is the article title; meta_title is not emitted separately. Lists remain YAML lists. SERP detail, metrics, and performance history stay in their CSV/research records; the outline stays in the Markdown body rather than front matter.

Rules:

• CSV is authoritative for metadata.
• Front matter is regenerated by sync/brief.
• The body is preserved.
• briefs.csv.article_path and briefs.csv.brief_path are distinct.
• publishing.csv owns WordPress metadata and QA snapshots.

Multi-site model

• One site_id per target domain, with a unique PID prefix.
• A workspace is a content program, not a site.
• A workspace can contain rows for multiple sites; site_id keeps ownership.
• WordPress connection fields are per site (wp_root, wp_url, wp_user, ssh_host).

note

The publish bridge was proven on opshell.dev. Other sites need their ACF/taxonomy contract inspected before the bridge is enabled. See WordPress Contract.