Concepts & Architectures — Content Standards

Tier: Concepts & Architectures | Reader phase: Understanding

What This Tier Is For

The Concepts & Architectures tier answers the “understand” questions a reader has before they configure or operate anything. Documents here do not contain step-by-step instructions — those belong in the Guides tier. Instead, this tier answers:

What is Aviatrix’s vision and framework? → CNSF
What problems does Aviatrix solve, for whom, and why does it matter? → Solution
What are the generic, reusable design patterns I can draw on? → Architecture
How has this been implemented for a specific business scenario? → Validated Design
What are the building blocks and platform capabilities I’m working with? → Component

How the Five Types Relate

CNSF ──► Solutions - - ► Architectures ◄- - Validated Designs
                │                                    │
                └ - - - ► Validated Designs          └──► Components
                │
                └ - - - ► Components

(Solid arrows: primary reading path. Dashed arrows: optional or reference links.) A reader entering at CNSF gets the strategic context. Solutions establish the business case and optionally link to Architecture patterns and Validated Designs. Architecture documents are a generic pattern library — they stand independently and are referenced from Validated Designs. Validated Designs document specific implemented outcomes aligned to business scenarios; they reference Architecture patterns and Component docs, and are more elaborate than Architecture docs — including workloads and the full system picture. Component docs provide the building-block and platform capability detail referenced throughout. Each document must stand alone for readers who enter mid-journey.

Document Types

Type	One-line definition	File
CNSF	The single strategic anchor for the tier — Aviatrix’s Cloud Native Security Fabric framework	cnsf.md
Solution	Makes the business case for a specific application of the platform	solution.md
Architecture	A generic, reusable design pattern — not tied to any specific solution or scenario	architecture.md
Validated Design	The conceptual outcome of a specific implemented deployment, aligned to a business scenario	validated-design.md
Component	The platform capabilities library — covers both deployable infrastructure components and major platform capabilities	component.md

Cross-Cutting Standards

The following standards apply to all document types in this tier. Every document must have at least one inbound link from an index page or related document. Orphaned documents create dead ends. When publishing a new document:

Add its path to the appropriate pages array in navigation-parser/subsections/ and run make clean && make all to regenerate docs.json — do not edit docs.json directly, it is a build output
Add a card for it in the parent section’s index.mdx
Link to it from any related documents in the tier

Image and diagram standards

Store diagrams in the nearest images/ directory (e.g., docs/cloud/concepts-architectures/components/images/)
Use SVG or PNG; minimum 1200px wide for topology diagrams
All diagrams must have a caption (H6 or italicized text immediately below the image)
ASCII diagrams are acceptable as an interim measure but should be replaced with proper images

Frontmatter

All documents require title, description, and keywords in frontmatter. See Frontmatter Standards for field definitions, formatting rules, and search optimization guidance.

Freshness and ownership

Each document should have a named owner (typically a Solutions Engineer or Technical Writer) responsible for reviewing it when the relevant product area changes. A document should be reviewed and updated within 30 days of a significant product release that affects its content.

What does NOT belong in this tier

Content	Where it belongs
Step-by-step configuration instructions (UI, CLI, Terraform)	Configuration Guides
Upgrade procedures and operational runbooks	Operational Guides
Terraform resource attribute reference	Terraform Reference
API endpoint documentation	API Reference
Release notes	Release Notices
Performance tuning configuration	Best Practices (Reference tier)