Skip to main content

​
Doc Type: Solution

Tier: Concepts & Architectures | Reader phase: Understanding
Back to tier overview: concepts-architectures/index.md

​
What it is

A Solution document makes the business case for a specific application of the Aviatrix platform. It frames a real problem faced by a real audience, explains why Aviatrix is the right answer, and demonstrates value through outcomes, metrics, and success stories. Solutions are not technical how-tos. They do not explain how to configure Aviatrix. They answer: Why should I care, and why should I choose Aviatrix to address this? There are two sub-types that follow the same template:
  • Business / Horizontal Solutions — Describe cross-industry problems (e.g., hybrid cloud connectivity, zero-trust networking, multi-cloud networking)
  • Industry Solutions — Describe the same class of problems for a specific vertical (e.g., financial services, healthcare, manufacturing)
Both sub-types use the same required sections. Industry solutions should tailor success stories and ROI examples to the vertical.

​
Goal

After reading a Solution document, the reader is convinced that this is their problem and that Aviatrix is worth evaluating as the solution. They can articulate the business case internally, and they are ready to explore architecture options, engage with the Aviatrix team, or navigate to the relevant Component and Architecture documents for technical depth.

​
Primary personas

​
When to create a new Solution

Create a new Solution document when:
  • There is a distinct, named business problem that a meaningful customer segment brings to Aviatrix
  • The problem has at least 2 defensible ROI data points
  • The solution is not already covered by an existing document at a different level of specificity
Do not create a solution for a product feature. Features belong in Component or Reference documentation.

​
Required sections

  1. Business Challenge — 2–4 sentences describing the pain. Write from the customer’s perspective. Be specific: name real consequences (regulatory penalties, breach costs, productivity drag). No Aviatrix mentions in this section.
  2. The Business Case for [Topic] — The case for why solving this problem matters (not why Aviatrix specifically). Use H3 subsections to organize 2–4 value dimensions (e.g., Risk Mitigation, Competitive Advantage, Operational Excellence). Each subsection should have 3–5 concrete bullet points. Bold the sub-benefit label (e.g., **Breach Prevention**).
  3. Industry Success Stories — 2–3 anonymized or named customer stories. Each follows this format:
    • H3: ### [Role/Industry Type] (e.g., Global Financial Institution, Regional Healthcare System)
    • Challenge: one sentence
    • Solution: one sentence
    • Results: 3–4 measurable outcomes as bullet points
  4. ROI and Business Impact — Quantified outcomes organized by category (Cost Avoidance, Operational Efficiency, Strategic Value). Use bold labels. Every figure should be citable or noted as “representative of customer outcomes.”
  5. Key Components — A brief section listing the Aviatrix components and capabilities central to this solution. Each entry is one sentence describing the role it plays in this context, followed by a link to its Component document. This section is not a technical deep-dive — it orients the reader on what they will be working with before they go deeper. Keep it to 3–6 entries.

​
Optional sections

  • Success Factors / Key Considerations — When the solution has common pitfalls or prerequisites worth calling out
  • Technology Landscape — When it’s useful to position Aviatrix relative to adjacent tools (e.g., “How Aviatrix complements your existing SIEM”)
  • Regulatory & Compliance Context — For highly regulated industry solutions

​
Tone & voice

Business-minded and outcome-focused. The reader is evaluating whether this problem is theirs and whether Aviatrix is worth their time. Write with authority and specificity. Avoid hedged language (“may help,” “could potentially”). Use active voice. Name real consequences. Let the data speak. This is the most persuasive document type in the tier — but persuasion comes from evidence, not enthusiasm. Avoid promotional language.

​
Length guidance

200–350 lines. Industry solutions trend shorter (150–200 lines); horizontal solutions trend longer (250–350 lines). If a solution exceeds 400 lines, consider whether it needs to be split by industry or sub-problem.

​
Frontmatter

See Frontmatter Standards for field definitions and formatting rules. Name the title after the outcome or strategy, not the product. Format: [Business Goal] Through [Approach]. Example: Security & Compliance Through Zero Trust Strategy.

​
Mintlify components

Solutions are primarily prose documents. Minimize component use to preserve the narrative flow. See the Style Guide for component definitions. The one exception to the prose-only rule is the Key Components section, where <CardGroup> + <Card> is appropriate — one card per component, with a one-sentence description and a link. Do not use <CardGroup> elsewhere in a Solution document. Avoid <Steps> and <Tabs> — they interrupt the business narrative.

​
Linking

Always provide all applicable links and let the reader decide their next step.
  • Link in from: CNSF (“Key Solutions” section), Solutions index page
  • Link out to:
    • Component documents for each capability listed in Key Components
    • Architecture documents where a relevant generic pattern applies (optional)
    • Validated Designs relevant to this solution (if they exist)
    • Configuration Guides for the primary configuration tasks involved (if they exist)

​
Dos and don’ts