System Architecture Manifest (SAM)

A composed architecture document aligning system topology with organizational reality.

Canonical Definition

System Architecture Manifest (SAM) is an organization-level architecture document composed from one or more System Topology Manifests (STM). which define systems, applications, and signals.

SAM layers principles, standards, constraints, and operational context on top of STM-defined system topology to describe how an organization builds, operates, and reasons about its systems.

STM defines what exists and how it relates.
SAM defines how the organization chooses to operate on top of that reality.

Why SAM Exists

System topology alone answers where systems sit and how they connect.
It does not answer:

• Why certain architectural decisions are preferred
• Which technologies are encouraged or avoided
• How systems are expected to be built and operated
• What constraints guide trade-offs
• Where risk, cost, and maintenance gravity live

SAM exists to make those realities explicit, shared, and machine-readable.

Relationship to System Topology Manifest (STM)

SAM is derived from STM.

• STM is authoritative for:

  • system identity
  • application identity
  • interfaces
  • signals (triggers, inputs, outputs)

• SAM is authoritative for:

  • architectural principles
  • coding and operational standards
  • platform and tooling preferences
  • dependency context
  • organizational constraints

The dependency is one-way:

STM  ──▶  SAM

System topology is derived during SAM composition from STM-declared signals.

SAM consumes one or more STM sources and derives system topology from declared application signals alongside organizational context such as principles, standards, and platform assumptions.

Application definitions (apps) must be copied verbatim from STM. Topology (graph_edges) must be derived deterministically from STM signals and must not be manually edited.

What a SAM Document Contains

A SAM document typically includes:

1. Architectural Principles

Explicit statements describing how decisions are evaluated and prioritized.

Examples:

• minimize operational debt
• prefer vendor-native solutions
• optimize for maintainability and clarity
• target revenue generation or cost reduction

2. Organizational Defaults and Constraints

Declared preferences and assumptions, such as:

• primary languages and runtimes
• integration platforms
• core systems
• AI and analytics tooling

These describe what is expected by default, not what is mandatory.

3. Coding and Engineering Standards

Shared conventions that guide consistency across systems, including:

• language philosophy
• error-handling approach
• structural patterns
• UI and frontend conventions
• logging and observability expectations

These standards explain how work is done, not how systems connect.

4. DevOps and Runtime Context

Operational assumptions and tooling, such as:

• deployment models
• hosting environments
• CI/CD
• testing strategy
• monitoring and logging infrastructure

This grounds architecture in real operating conditions.

5. System Inventory (Referenced, Not Redefined)

SAM references systems defined in STM and may:

• group them into domains or capabilities
• annotate them with standards, ownership, or risk
• apply organizational lenses (e.g., ETL, customer-facing, revenue-critical)

Topology itself remains owned by STM.

6. Derived Views (Optional)

SAM may define filtered perspectives over the system graph, such as:

• high-risk systems
• legacy clusters
• revenue-impacting paths
• integration-heavy surfaces

These are derived interpretations, not new graphs or topology definitions.

What SAM Explicitly Does Not Do

SAM does not:

• define system topology
• declare triggers, inputs, or outputs
• describe execution logic or workflows
• replace STM, SFL, or runtime tooling

SAM is context, not control flow.

Composition Model

SAM is intended to be composed programmatically or manually from STM plus organizational inputs.

Typical composition steps include:

1. Load one or more STM manifests
2. Resolve system identities
3. Apply organizational principles and standards
4. Generate a consolidated architecture manifest

SAM favors determinism and explicit declaration over inference.

Default Distribution Format

The default SAM distribution format is a flattened bundle.

In this format:

• apps are copied verbatim from STM
• graph_edges are derived deterministically during SAM composition
• STM provenance (source + content hash) is preserved

This allows SAM to function as a single, self-contained artifact for AI guardrails and analysis without requiring consumers to load STM separately.

Intended Use Cases

SAM is designed to support:

• architectural decision-making
• system discovery and onboarding
• AI-assisted reasoning bounded by reality
• topology-aware visualization
• impact and dependency analysis
• long-term institutional memory

It is not a replacement for diagrams, tickets, or documentation — it is a structural reference point they can rely on.

Repository Structure (Initial)

sam/
├─ README.md          # This document
├─ docs/              # Composition rules and scope clarification
├─ examples/          # Example SAM outputs
└─ tools/             # Optional generators and validators

Guiding Principle

STM describes the system landscape.
SAM describes how the organization chooses to live within it.

Runtime Layer

This system uses MOCA (Memory-Oriented Cognitive Architecture) as a runtime and integration layer.

MOCA is independently usable and is not specific to this project.

https://github.com/MemoryOrientedCognitiveArchitecture/memory-oriented-cognitive-architecture

Contributing

We welcome contributions to expand and improve the System Architecture Manifest project. If you’re interested, please check out the contributing guidelines for more information.

Contact

• Author: William Shostak (https://github.com/wshostak)

License

This project is licensed under the ISC License — see the LICENSE file for more details.

Copyright (c) 2025 William Shostak