Skip to content

docs(profile): finish public architecture/documentation gaps #5

Description

@ClaudiaFang

Current state

This issue is partially implemented on current main and should no longer be treated as a greenfield documentation task.

Already present:

  • organization profile describing public services and the public/private implementation boundary;
  • docs/infrastructure-overview.md with a sanitized public infrastructure overview;
  • docs/case-studies/heaven-platform.md plus a case-study index;
  • profile links to the infrastructure overview, Heaven Platform case study, tools/plugins, and service status;
  • a lightweight public service/project catalog in the profile README.

Remaining goal

Close only the gaps that materially improve public understanding without duplicating the profile or exposing privileged topology/configuration.

Remaining audit

  • Decide whether a separate implementation/engineering guide is still useful beyond infrastructure-overview.md and the Heaven Platform case study.
  • If useful, document reusable engineering principles at a safe abstraction level: IaC, CI/CD, observability, testing, and agent-assisted workflow — without inventories, private network details, credentials, or operational runbooks.
  • Audit the profile's public service/project catalog for current links and remove stale entries.
  • Verify every public architecture document still respects the public-service / private-implementation boundary.
  • Avoid creating a second generic architecture document if the existing overview + case study already communicate the intended model.

Acceptance criteria

  • No duplicated architecture pages with overlapping purpose.
  • Profile links point to current public documents/services.
  • Public docs explain the engineering model without private host/network/inventory/credential details.
  • A separate implementation guide is added only if it has a distinct audience/purpose; otherwise this issue may close after the audit.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions