Skip to content

Commit 03cb2bd

Browse files
gouravjshahclaude
gouravjshah
and
claude
committed
docs: Clean up and organize architecture documentation
- Add comprehensive architecture overview page - Add all 4 architecture docs to sidebar (composable-design, context-injection, multi-model-consensus, multi-tenant-agentflows) - Add proper frontmatter with sidebar labels to architecture docs - Remove developer-focused docs from user-facing Guides section (local-testing, testing-mcp) - Exclude dev/, user/, and other internal docs from public site - Add star callout to all documentation pages via DocItem wrapper - Fix broken anchor link in CLI_REFERENCE.md 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent c2558dc commit 03cb2bd

File tree

10 files changed

+179
-4
lines changed

10 files changed

+179
-4
lines changed

‎docs/architecture/composable-design.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
sidebar_label: Composable Design
3+
sidebar_position: 2
4+
---
5+
16
# Composable Architecture
27

38
AOF follows a simple, composable model with four core concepts.

‎docs/architecture/context-injection.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
sidebar_label: Context Injection
3+
sidebar_position: 3
4+
---
5+
16
# Context Injection Architecture
27

38
This document provides a deep dive into AOF's context injection system, which enables the same agent to operate safely across different environments, clusters, and security boundaries.

‎docs/architecture/index.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
sidebar_label: Overview
3+
sidebar_position: 1
4+
---
5+
6+
# Architecture Overview
7+
8+
AOF's architecture is designed around composability, safety, and multi-model intelligence. This section covers the core architectural concepts that power the framework.
9+
10+
## Core Principles
11+
12+
1. **Composability**: Build complex workflows from simple, reusable components
13+
2. **Safety**: Context injection ensures environment boundaries are respected
14+
3. **Intelligence**: Multi-model consensus improves accuracy and reduces errors
15+
4. **Scalability**: Multi-tenant routing supports enterprise deployments
16+
17+
## Architecture Documents
18+
19+
### [Composable Design](./composable-design.md)
20+
21+
The foundational architecture of AOF, organized into four layers:
22+
23+
```
24+
Layer 4: TRIGGERS ─ Platform routing (Slack, Discord, Teams, etc.)
25+
Layer 3: FLOWS ─ Multi-step workflows with orchestration
26+
Layer 2: FLEETS ─ Agent composition for collaboration
27+
Layer 1: AGENTS ─ Single-purpose AI specialists
28+
```
29+
30+
Each layer builds on the previous, enabling you to start simple and add complexity as needed.
31+
32+
### [Context Injection](./context-injection.md)
33+
34+
How AOF ensures the same agent can operate safely across different environments:
35+
36+
- **Environment boundaries**: Isolate production from staging
37+
- **Approval workflows**: Require human approval for destructive operations
38+
- **Rate limiting**: Prevent runaway agents
39+
- **Audit trails**: Track all agent actions for compliance
40+
41+
### [Multi-Model Consensus](./multi-model-consensus.md)
42+
43+
Leverage multiple AI models to improve accuracy:
44+
45+
- **Cross-validation**: Multiple models verify each other's conclusions
46+
- **Weighted voting**: Assign different weights to model opinions
47+
- **Confidence scoring**: Know when to trust the output
48+
- **Fault tolerance**: One wrong model gets outvoted
49+
50+
### [Multi-Tenant Flows](./multi-tenant-agentflows.md)
51+
52+
Scale AOF across organizations, teams, and projects:
53+
54+
- **Platform routing**: Different platforms → different agents
55+
- **Channel isolation**: Team-specific agent configurations
56+
- **User/role matching**: Admin vs developer permissions
57+
- **Organization boundaries**: Enterprise multi-org support
58+
59+
## Visual Overview
60+
61+
```
62+
┌─────────────────────────────────────────────────────────────────────────────┐
63+
│ AOF Architecture │
64+
│ │
65+
│ ┌───────────────────────────────────────────────────────────────────────┐ │
66+
│ │ TRIGGER LAYER │ │
67+
│ │ Slack │ Discord │ Teams │ Telegram │ WhatsApp │ GitHub │ │
68+
│ └─────────────────────────────────────────────────────────────────────────┘│
69+
│ │ │
70+
│ ▼ │
71+
│ ┌───────────────────────────────────────────────────────────────────────┐ │
72+
│ │ FLOW LAYER │ │
73+
│ │ Multi-step workflows with nodes, conditions, and approval gates │ │
74+
│ └─────────────────────────────────────────────────────────────────────────┘│
75+
│ │ │
76+
│ ▼ │
77+
│ ┌───────────────────────────────────────────────────────────────────────┐ │
78+
│ │ FLEET LAYER │ │
79+
│ │ Agent composition: collectors → analyzers → synthesizers │ │
80+
│ └─────────────────────────────────────────────────────────────────────────┘│
81+
│ │ │
82+
│ ▼ │
83+
│ ┌───────────────────────────────────────────────────────────────────────┐ │
84+
│ │ AGENT LAYER │ │
85+
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
86+
│ │ │ k8s-ops │ │ aws-ops │ │ docker │ │terraform│ │ git │ ... │ │
87+
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
88+
│ └─────────────────────────────────────────────────────────────────────────┘│
89+
│ │
90+
│ ┌───────────────────────────────────────────────────────────────────────┐ │
91+
│ │ CROSS-CUTTING CONCERNS │ │
92+
│ │ Context Injection │ Multi-Model Consensus │ Multi-Tenant Routing │ │
93+
│ └─────────────────────────────────────────────────────────────────────────┘│
94+
└─────────────────────────────────────────────────────────────────────────────┘
95+
```
96+
97+
## Getting Started
98+
99+
- **New to AOF?** Start with [Composable Design](./composable-design.md) to understand the core concepts
100+
- **Deploying to production?** Read [Context Injection](./context-injection.md) for safety best practices
101+
- **Building RCA workflows?** See [Multi-Model Consensus](./multi-model-consensus.md)
102+
- **Enterprise deployment?** Check [Multi-Tenant Flows](./multi-tenant-agentflows.md)

‎docs/architecture/multi-model-consensus.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
sidebar_label: Multi-Model Consensus
3+
sidebar_position: 4
4+
---
5+
16
# Multi-Model Consensus Architecture
27

38
## Overview

‎docs/architecture/multi-tenant-agentflows.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,8 @@
1+
---
2+
sidebar_label: Multi-Tenant Flows
3+
sidebar_position: 5
4+
---
5+
16
# Multi-Tenant AgentFlow Architecture
27

38
This document describes the architecture for running multiple AgentFlows simultaneously to support different projects, bots, organizations, and divisions within a single AOF deployment.

‎docs/user/CLI_REFERENCE.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -324,7 +324,7 @@ When `flows.enabled: true`, incoming messages are matched against AgentFlow file
324324

325325
Each flow can specify its own execution context (kubeconfig, namespace, environment variables).
326326

327-
See [AgentFlow Spec](../reference/agentflow-spec.md#trigger-filtering-multi-tenant-routing) for routing configuration.
327+
See [Multi-Tenant Flows](../architecture/multi-tenant-agentflows.md) for routing configuration.
328328

329329
### validate
330330

‎docusaurus-site/docusaurus.config.ts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,9 @@ const config: Config = {
4848
'LLM_*.md',
4949
'RUVECTOR_*.md',
5050
'DOCUMENTATION_INDEX.md',
51-
// Keep architecture/multi-model-consensus.md but exclude technical arch docs
51+
'USER_README.md',
52+
'README.md',
53+
// Keep architecture docs but exclude technical internal docs
5254
'architecture/README.md',
5355
'architecture/ADR-*.md',
5456
'architecture/*-crd.yaml',
@@ -60,9 +62,15 @@ const config: Config = {
6062
'architecture/resource-type-specifications.md',
6163
'architecture/rust-implementation.md',
6264
'architecture/usage-examples.md',
65+
// Developer/contributor docs (not user-facing)
66+
'guides/local-testing.md',
67+
'guides/testing-mcp.md',
68+
// Internal directories
6369
'schemas/**',
6470
'agentflow/**',
6571
'internal/**',
72+
'user/**',
73+
'dev/**',
6674
],
6775
// Please change this to your repo.
6876
// Remove this to remove the "edit this page" links.

‎docusaurus-site/sidebars.ts‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,11 @@ const sidebars: SidebarsConfig = {
4747
type: 'category',
4848
label: 'Architecture',
4949
items: [
50+
'architecture/index',
51+
'architecture/composable-design',
52+
'architecture/context-injection',
5053
'architecture/multi-model-consensus',
54+
'architecture/multi-tenant-agentflows',
5155
],
5256
},
5357
{
@@ -70,8 +74,6 @@ const sidebars: SidebarsConfig = {
7074
'guides/quickstart-discord',
7175
'guides/approval-workflow',
7276
'guides/deployment',
73-
'guides/local-testing',
74-
'guides/testing-mcp',
7577
],
7678
},
7779
{

‎docusaurus-site/src/theme/DocItem/Content/index.tsx‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
import React from 'react';
2+
import Content from '@theme-original/DocItem/Content';
3+
import type ContentType from '@theme/DocItem/Content';
4+
import type {WrapperProps} from '@docusaurus/types';
5+
import Admonition from '@theme/Admonition';
6+
7+
type Props = WrapperProps<typeof ContentType>;
8+
9+
export default function ContentWrapper(props: Props): React.JSX.Element {
10+
return (
11+
<>
12+
<Admonition type="tip" title="Like AOF? Give us a star!">
13+
If you find AOF useful, please{' '}
14+
<a href="https://github.com/agenticdevops/aof" target="_blank" rel="noopener noreferrer">
15+
star us on GitHub
16+
</a>
17+
. It helps us reach more developers and grow the community.
18+
</Admonition>
19+
<Content {...props} />
20+
</>
21+
);
22+
}

‎docusaurus-site/src/theme/MDXComponents.tsx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
import React from 'react';
2+
import MDXComponents from '@theme-original/MDXComponents';
3+
import Admonition from '@theme/Admonition';
4+
5+
// Star callout component that can be used in any MDX file
6+
function StarCallout() {
7+
return (
8+
<Admonition type="tip" title="Like AOF? Give us a star!">
9+
If you find AOF useful, please{' '}
10+
<a href="https://github.com/agenticdevops/aof" target="_blank" rel="noopener noreferrer">
11+
star us on GitHub
12+
</a>
13+
. It helps us reach more developers and grow the community.
14+
</Admonition>
15+
);
16+
}
17+
18+
export default {
19+
...MDXComponents,
20+
StarCallout,
21+
};

0 commit comments

Comments
 (0)