Skip to content
Ghost AI WriterEditorial control plane Operator sign in

Developer notes

Add behavior without erasing evidence.

The implementation keeps the pipeline state machine stable while adding durable ledgers, explicit operator controls and deterministic static output.

Runtime boundaries

Public shell, protected control plane

/Public marketingNo operator bootstrap→/loginAuthenticationSame-origin redirects only→/dashboard/Operator UIFlask data + React/shadcn

Source of truth

State is additive and attributable

Run journal

Compatibility state

Run lifecycle, results and immutable manifest remain backward readable.

usage-ledger.sqlite3

AI metering

Request-level token, stage, model and event-time rate evidence.

operations.sqlite3

Operational evidence

Run events, articles, maintenance operations and publish attempts.

JSON repositories

Operator state

Clusters, authors and duplicate-index metadata use revision-aware mutations.

Code ownership

Follow the boundary that owns the behavior

app/pipeline.py

Canonical content pipeline

Keyword execution order, Ghost handoff, local commit and batch linker entry point.

web/routes/

HTTP contracts

Authentication, validation, CSRF-protected mutations and sanitized bootstrap payloads.

web/runner.py

Run orchestration

Immutable manifests, background execution, cooperative cancellation and recovery.

frontend/src/

Operator presentation

React/shadcn pages consume server truth; they do not invent pipeline state.

core/usage.py

AI metering

Event-time catalog pricing, attribution scopes and ledger summaries.

services/ghost_client.py

Ghost boundary

Single-shot writes, safe reads and uncertain-publish reconciliation support.

services/static_site_builder.py

Artifact boundary

Published-post snapshot, Node renderer invocation and immutable artifact evidence.

tools/build_railway_marketing.mjs

Public pages

Generates repository-owned Railway marketing and product documentation shells.

Extension rules

Keep the contracts boring

  • Route every provider request through its existing adapter and sanitized ledger boundary.
  • Never add an implicit all-pending queue fallback or retry an uncertain Ghost POST.
  • Keep public routes outside operator-state bootstrap and protect every mutation with auth and CSRF.
  • Use stable cluster/topic IDs and repository revisions for mutable JSON state.
  • Regenerate committed UI/marketing assets and require a clean diff in CI.
  • Add unit, integration, Playwright, axe and documentation-truth coverage proportional to the change.

Local verification

Reproduce the release gates before pushing

python -m pytest
npm run lint
npm run typecheck
npm run build
npm test --workspace=static_generator
npm run build:railway-marketing
npm run test:e2e --workspace=frontend

CI additionally verifies the Python lock, dependency integrity, compilation, committed-secret policy, generated-asset cleanliness and the production entry point.

Release gates

Every deploy proves its identity.

Compilation, locked dependencies, audits, secret scanning, renderer security, frontend reproducibility, accessibility, branch coverage and the Railway deployment SHA must pass before staging evidence is accepted.