198 lines
6.3 KiB
Markdown
198 lines
6.3 KiB
Markdown
# Introduction
|
||
|
||
The ABC Pattern is a universal architectural model for structuring cloud
|
||
infrastructure in a way that is predictable, explicit, and safe for automated
|
||
reasoning. It defines a small set of composable building blocks and a strict set
|
||
of rules governing how those blocks relate, communicate, and evolve. The result
|
||
is an architecture that is easy to understand, easy to validate, and easy to
|
||
generate or transform using both human and machine agents.
|
||
|
||
ABC is intentionally tool‑agnostic and cloud‑agnostic. It does not prescribe
|
||
specific services, resource types, or implementation languages. Instead, it
|
||
defines a semantic architecture model that can be mapped onto any
|
||
infrastructure-as-code system, including imperative tools (such as CDK) and
|
||
declarative tools (such as Terraform).
|
||
|
||
At its core, ABC is built on three foundational ideas:
|
||
|
||
**1. A strict hierarchical structure**
|
||
Every ABC architecture is composed of three construct types:
|
||
|
||
* ApplicationStack - the root of the system
|
||
* Logical Units - functional domains
|
||
* Resource Groups - cohesive clusters of cloud resources
|
||
|
||
This hierarchy forms a strict tree with no lateral references, ensuring clarity
|
||
and isolation.
|
||
|
||
**2. Explicit contracts and deterministic data flow**
|
||
|
||
Every construct defines:
|
||
|
||
* an Input Contract (what it needs)
|
||
* an Output Contract (what it produces)
|
||
|
||
Data flows only in two directions:
|
||
|
||
* Capturing Down - parents pass data to children
|
||
* Bubbling Up - children return data to parents
|
||
|
||
This eliminates hidden dependencies and makes the architecture fully analyzable.
|
||
|
||
**3. A stable foundation for automation**
|
||
|
||
Because ABC is explicit, typed, and deterministic, it is uniquely suited for:
|
||
|
||
* automated code generation
|
||
* architecture validation
|
||
* refactoring and transformation
|
||
* multi‑cloud portability
|
||
* agent‑driven reasoning
|
||
|
||
ABC is designed to be the intermediate representation (IR) for infrastructure,
|
||
something like the “AST of cloud architecture”.
|
||
|
||
## Purpose and Philosophy
|
||
|
||
The ABC Pattern exists to solve a fundamental problem in cloud architecture:
|
||
infrastructure is too implicit.
|
||
|
||
* Dependencies are hidden.
|
||
* Data flow is unclear.
|
||
* Modules are entangled.
|
||
* Refactoring is risky.
|
||
* Automation is fragile.
|
||
|
||
ABC replaces this with a model that is:
|
||
|
||
* explicit,
|
||
* typed,
|
||
* hierarchical,
|
||
* deterministic,
|
||
* verifiable, and
|
||
* portable
|
||
|
||
It is designed to be understood by humans, validated by tools, and generated by
|
||
agents.
|
||
|
||
## Contents
|
||
|
||
* [Concepts](concepts.md)
|
||
* [Abstract Model](model.md)
|
||
* [Rules](rules/README.md)
|
||
* [Schema](schema.md)
|
||
* [Canonical Example](example.md)
|
||
* [Profiles](profiles/README.md)
|
||
|
||
## Usage
|
||
|
||
The Abstract Base Cloud Specification is written for both human engineers and
|
||
automated agents. It provides a clear, explicit architectural model that people
|
||
can read, understand, and apply directly, while also offering the structure and
|
||
determinism that agent‑driven tools require.
|
||
|
||
### Manual
|
||
|
||
Familarize yourself with one of the specification’s implementation profiles.
|
||
|
||
### Agent-driven
|
||
|
||
The specification is designed to be consumed directly by agent‑driven tools
|
||
compatible with [AGENTS.md](https://agents.md). It can be referenced either
|
||
locally (via Git submodule) or remotely (via the hosted version). Both
|
||
approaches expose the same structure:
|
||
|
||
* `README.md` - the entrypoint of the specification
|
||
* `AGENTS.md` - operational guidance for LLM agents
|
||
|
||
Your own project’s `AGENTS.md` should reference the specification’s
|
||
`AGENTS.md` directly, so your agents always operate with the canonical rules
|
||
and behaviors.
|
||
|
||
#### IMPORTANT
|
||
Implementation profiles of the specification only pose minor coding
|
||
guidelines. You are responsible for setting broader rules for managing your
|
||
repository and codebase.
|
||
|
||
#### Using the Specification as a Git Submodule
|
||
|
||
You can embed the specification directly into your repository:
|
||
|
||
``bash
|
||
git submodule add https://bitbucket.org/byteb4rb1e/abc-ai.git vendor/abc-ai
|
||
``
|
||
|
||
This makes the spec available locally at `./vendor/abc-ai/`.
|
||
|
||
Your agents can now reference the spec’s entrypoint and agent guide via relative
|
||
paths:
|
||
|
||
* `./vendor/abc-ai/README.md`
|
||
* `./vendor/abc-ai/AGENTS.md`
|
||
|
||
This is the recommended approach for offline, air‑gapped, or privacy‑sensitive
|
||
environments.
|
||
|
||
#### Using the Hosted Specification
|
||
|
||
If you prefer not to vendor the spec, you can reference the hosted version:
|
||
|
||
Entry point:
|
||
[https://spec.tiararodney.com/abc/markdown/README.md](https://spec.tiararodney.com/abc/markdown/README.md)
|
||
|
||
Agent guide:
|
||
[https://spec.tiararodney.com/abc/markdown/AGENTS.md](https://spec.tiararodney.com/abc/markdown/AGENTS.md)
|
||
|
||
Agents can fetch these URLs directly when resolving rules, profiles, or schema
|
||
definitions.
|
||
|
||
#### Referencing the Specification from Your Own AGENTS.md
|
||
|
||
Your project’s AGENTS.md should explicitly instruct agents to load and follow
|
||
the ABC specification. A typical integration looks like this:
|
||
|
||
#### IMPORTANT
|
||
You MUST specify an ABC implementation profile in your `AGENTS.md`.
|
||
|
||
```markdown
|
||
# Agent Guide for This Project
|
||
|
||
This project uses the **Abstract Base Cloud (ABC)** pattern with the
|
||
Typescript CDK implementation profile for all architecture generation,
|
||
validation, and transformation.
|
||
|
||
Agents MUST follow the official ABC Specification and its agent guide:
|
||
|
||
* Specification entrypoint: `./vendor/abc-ai/README.md`
|
||
(or the hosted version if not using a submodule)
|
||
* Agent instructions: `./vendor/abc-ai/AGENTS.md`
|
||
|
||
Agents MUST treat the ABC Specification as authoritative for authoring
|
||
Infrastructure-as-Code.
|
||
|
||
When generating infrastructure code, agents MUST:
|
||
|
||
1. Load the ABC Specification’s `AGENTS.md`.
|
||
2. Apply the rules and behaviors defined there.
|
||
3. Use the implementation profile appropriate for the target IaC tool.
|
||
4. Validate all generated output against the ABC Schema.
|
||
```
|
||
|
||
## License
|
||
|
||
The Abstract Base Cloud Specification is licensed under the
|
||
Creative Commons Attribution–NoDerivatives 4.0 International License (CC‑BY‑ND 4.0).
|
||
|
||
You are free to:
|
||
|
||
* copy and redistribute the specification in any medium or format
|
||
* use it for commercial or non‑commercial purposes
|
||
|
||
Under the following terms:
|
||
|
||
* Attribution — You must give appropriate credit and provide a link to the
|
||
license.
|
||
* No Derivatives — If you remix, transform, or build upon the material, you may
|
||
not distribute the modified specification.
|
||
|
||
See the full license text in [LICENSE](LICENSE).
|