init
This commit is contained in:
Tiara Rodney
parent
0d674783f6
commit
3cffcc9ee4
18 changed files with 2938 additions and 0 deletions
2
.gitignore
vendored
2
.gitignore
vendored
|
|
@ -0,0 +1,2 @@
|
|||
/build/
|
||||
/dist/doctrees/
|
||||
18
Pipfile
Normal file
18
Pipfile
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
[[source]]
|
||||
url = "https://pypi.org/simple"
|
||||
verify_ssl = true
|
||||
name = "pypi"
|
||||
|
||||
[packages]
|
||||
sphinx = "==9.1.0"
|
||||
sphinx-last-updated-by-git = "*"
|
||||
sphinx-markdown-builder = "*"
|
||||
|
||||
[dev-packages]
|
||||
|
||||
[requires]
|
||||
python_version = "3.13"
|
||||
|
||||
[scripts]
|
||||
build-html = "sphinx-build -b html src/ build/html"
|
||||
build-md = "sphinx-build -M markdown src/ dist/"
|
||||
422
Pipfile.lock
generated
Normal file
422
Pipfile.lock
generated
Normal file
|
|
@ -0,0 +1,422 @@
|
|||
{
|
||||
"_meta": {
|
||||
"hash": {
|
||||
"sha256": "a889c35529339553277566894ad1f7630f478a0a996bee97ad7e704e938b9146"
|
||||
},
|
||||
"pipfile-spec": 6,
|
||||
"requires": {
|
||||
"python_version": "3.13"
|
||||
},
|
||||
"sources": [
|
||||
{
|
||||
"name": "pypi",
|
||||
"url": "https://pypi.org/simple",
|
||||
"verify_ssl": true
|
||||
}
|
||||
]
|
||||
},
|
||||
"default": {
|
||||
"alabaster": {
|
||||
"hashes": [
|
||||
"sha256:c00dca57bca26fa62a6d7d0a9fcce65f3e026e9bfe33e9c538fd3fbb2144fd9e",
|
||||
"sha256:fc6786402dc3fcb2de3cabd5fe455a2db534b371124f1f21de8731783dec828b"
|
||||
],
|
||||
"markers": "python_version >= '3.10'",
|
||||
"version": "==1.0.0"
|
||||
},
|
||||
"babel": {
|
||||
"hashes": [
|
||||
"sha256:b80b99a14bd085fcacfa15c9165f651fbb3406e66cc603abf11c5750937c992d",
|
||||
"sha256:e2b422b277c2b9a9630c1d7903c2a00d0830c409c59ac8cae9081c92f1aeba35"
|
||||
],
|
||||
"markers": "python_version >= '3.8'",
|
||||
"version": "==2.18.0"
|
||||
},
|
||||
"certifi": {
|
||||
"hashes": [
|
||||
"sha256:9943707519e4add1115f44c2bc244f782c0249876bf51b6599fee1ffbedd685c",
|
||||
"sha256:ac726dd470482006e014ad384921ed6438c457018f4b3d204aea4281258b2120"
|
||||
],
|
||||
"markers": "python_version >= '3.7'",
|
||||
"version": "==2026.1.4"
|
||||
},
|
||||
"charset-normalizer": {
|
||||
"hashes": [
|
||||
"sha256:027f6de494925c0ab2a55eab46ae5129951638a49a34d87f4c3eda90f696b4ad",
|
||||
"sha256:077fbb858e903c73f6c9db43374fd213b0b6a778106bc7032446a8e8b5b38b93",
|
||||
"sha256:0a98e6759f854bd25a58a73fa88833fba3b7c491169f86ce1180c948ab3fd394",
|
||||
"sha256:0d3d8f15c07f86e9ff82319b3d9ef6f4bf907608f53fe9d92b28ea9ae3d1fd89",
|
||||
"sha256:0f04b14ffe5fdc8c4933862d8306109a2c51e0704acfa35d51598eb45a1e89fc",
|
||||
"sha256:11d694519d7f29d6cd09f6ac70028dba10f92f6cdd059096db198c283794ac86",
|
||||
"sha256:194f08cbb32dc406d6e1aea671a68be0823673db2832b38405deba2fb0d88f63",
|
||||
"sha256:1bee1e43c28aa63cb16e5c14e582580546b08e535299b8b6158a7c9c768a1f3d",
|
||||
"sha256:21d142cc6c0ec30d2efee5068ca36c128a30b0f2c53c1c07bd78cb6bc1d3be5f",
|
||||
"sha256:2437418e20515acec67d86e12bf70056a33abdacb5cb1655042f6538d6b085a8",
|
||||
"sha256:244bfb999c71b35de57821b8ea746b24e863398194a4014e4c76adc2bbdfeff0",
|
||||
"sha256:2677acec1a2f8ef614c6888b5b4ae4060cc184174a938ed4e8ef690e15d3e505",
|
||||
"sha256:277e970e750505ed74c832b4bf75dac7476262ee2a013f5574dd49075879e161",
|
||||
"sha256:2aaba3b0819274cc41757a1da876f810a3e4d7b6eb25699253a4effef9e8e4af",
|
||||
"sha256:2b7d8f6c26245217bd2ad053761201e9f9680f8ce52f0fcd8d0755aeae5b2152",
|
||||
"sha256:2c9d3c380143a1fedbff95a312aa798578371eb29da42106a29019368a475318",
|
||||
"sha256:3162d5d8ce1bb98dd51af660f2121c55d0fa541b46dff7bb9b9f86ea1d87de72",
|
||||
"sha256:31fd66405eaf47bb62e8cd575dc621c56c668f27d46a61d975a249930dd5e2a4",
|
||||
"sha256:362d61fd13843997c1c446760ef36f240cf81d3ebf74ac62652aebaf7838561e",
|
||||
"sha256:376bec83a63b8021bb5c8ea75e21c4ccb86e7e45ca4eb81146091b56599b80c3",
|
||||
"sha256:44c2a8734b333e0578090c4cd6b16f275e07aa6614ca8715e6c038e865e70576",
|
||||
"sha256:47cc91b2f4dd2833fddaedd2893006b0106129d4b94fdb6af1f4ce5a9965577c",
|
||||
"sha256:4902828217069c3c5c71094537a8e623f5d097858ac6ca8252f7b4d10b7560f1",
|
||||
"sha256:4bd5d4137d500351a30687c2d3971758aac9a19208fc110ccb9d7188fbe709e8",
|
||||
"sha256:4fe7859a4e3e8457458e2ff592f15ccb02f3da787fcd31e0183879c3ad4692a1",
|
||||
"sha256:542d2cee80be6f80247095cc36c418f7bddd14f4a6de45af91dfad36d817bba2",
|
||||
"sha256:554af85e960429cf30784dd47447d5125aaa3b99a6f0683589dbd27e2f45da44",
|
||||
"sha256:5833d2c39d8896e4e19b689ffc198f08ea58116bee26dea51e362ecc7cd3ed26",
|
||||
"sha256:5947809c8a2417be3267efc979c47d76a079758166f7d43ef5ae8e9f92751f88",
|
||||
"sha256:5ae497466c7901d54b639cf42d5b8c1b6a4fead55215500d2f486d34db48d016",
|
||||
"sha256:5bd2293095d766545ec1a8f612559f6b40abc0eb18bb2f5d1171872d34036ede",
|
||||
"sha256:5bfbb1b9acf3334612667b61bd3002196fe2a1eb4dd74d247e0f2a4d50ec9bbf",
|
||||
"sha256:5cb4d72eea50c8868f5288b7f7f33ed276118325c1dfd3957089f6b519e1382a",
|
||||
"sha256:5dbe56a36425d26d6cfb40ce79c314a2e4dd6211d51d6d2191c00bed34f354cc",
|
||||
"sha256:5f819d5fe9234f9f82d75bdfa9aef3a3d72c4d24a6e57aeaebba32a704553aa0",
|
||||
"sha256:64b55f9dce520635f018f907ff1b0df1fdc31f2795a922fb49dd14fbcdf48c84",
|
||||
"sha256:6515f3182dbe4ea06ced2d9e8666d97b46ef4c75e326b79bb624110f122551db",
|
||||
"sha256:65e2befcd84bc6f37095f5961e68a6f077bf44946771354a28ad434c2cce0ae1",
|
||||
"sha256:6aee717dcfead04c6eb1ce3bd29ac1e22663cdea57f943c87d1eab9a025438d7",
|
||||
"sha256:6b39f987ae8ccdf0d2642338faf2abb1862340facc796048b604ef14919e55ed",
|
||||
"sha256:6e1fcf0720908f200cd21aa4e6750a48ff6ce4afe7ff5a79a90d5ed8a08296f8",
|
||||
"sha256:74018750915ee7ad843a774364e13a3db91682f26142baddf775342c3f5b1133",
|
||||
"sha256:74664978bb272435107de04e36db5a9735e78232b85b77d45cfb38f758efd33e",
|
||||
"sha256:74bb723680f9f7a6234dcf67aea57e708ec1fbdf5699fb91dfd6f511b0a320ef",
|
||||
"sha256:752944c7ffbfdd10c074dc58ec2d5a8a4cd9493b314d367c14d24c17684ddd14",
|
||||
"sha256:778d2e08eda00f4256d7f672ca9fef386071c9202f5e4607920b86d7803387f2",
|
||||
"sha256:780236ac706e66881f3b7f2f32dfe90507a09e67d1d454c762cf642e6e1586e0",
|
||||
"sha256:798d75d81754988d2565bff1b97ba5a44411867c0cf32b77a7e8f8d84796b10d",
|
||||
"sha256:799a7a5e4fb2d5898c60b640fd4981d6a25f1c11790935a44ce38c54e985f828",
|
||||
"sha256:7a32c560861a02ff789ad905a2fe94e3f840803362c84fecf1851cb4cf3dc37f",
|
||||
"sha256:7c308f7e26e4363d79df40ca5b2be1c6ba9f02bdbccfed5abddb7859a6ce72cf",
|
||||
"sha256:7fa17817dc5625de8a027cb8b26d9fefa3ea28c8253929b8d6649e705d2835b6",
|
||||
"sha256:81d5eb2a312700f4ecaa977a8235b634ce853200e828fbadf3a9c50bab278328",
|
||||
"sha256:82004af6c302b5d3ab2cfc4cc5f29db16123b1a8417f2e25f9066f91d4411090",
|
||||
"sha256:837c2ce8c5a65a2035be9b3569c684358dfbf109fd3b6969630a87535495ceaa",
|
||||
"sha256:840c25fb618a231545cbab0564a799f101b63b9901f2569faecd6b222ac72381",
|
||||
"sha256:8a6562c3700cce886c5be75ade4a5db4214fda19fede41d9792d100288d8f94c",
|
||||
"sha256:8af65f14dc14a79b924524b1e7fffe304517b2bff5a58bf64f30b98bbc5079eb",
|
||||
"sha256:8ef3c867360f88ac904fd3f5e1f902f13307af9052646963ee08ff4f131adafc",
|
||||
"sha256:94537985111c35f28720e43603b8e7b43a6ecfb2ce1d3058bbe955b73404e21a",
|
||||
"sha256:99ae2cffebb06e6c22bdc25801d7b30f503cc87dbd283479e7b606f70aff57ec",
|
||||
"sha256:9a26f18905b8dd5d685d6d07b0cdf98a79f3c7a918906af7cc143ea2e164c8bc",
|
||||
"sha256:9b35f4c90079ff2e2edc5b26c0c77925e5d2d255c42c74fdb70fb49b172726ac",
|
||||
"sha256:9cd98cdc06614a2f768d2b7286d66805f94c48cde050acdbbb7db2600ab3197e",
|
||||
"sha256:9d1bb833febdff5c8927f922386db610b49db6e0d4f4ee29601d71e7c2694313",
|
||||
"sha256:9f7fcd74d410a36883701fafa2482a6af2ff5ba96b9a620e9e0721e28ead5569",
|
||||
"sha256:a59cb51917aa591b1c4e6a43c132f0cdc3c76dbad6155df4e28ee626cc77a0a3",
|
||||
"sha256:a61900df84c667873b292c3de315a786dd8dac506704dea57bc957bd31e22c7d",
|
||||
"sha256:a79cfe37875f822425b89a82333404539ae63dbdddf97f84dcbc3d339aae9525",
|
||||
"sha256:a8a8b89589086a25749f471e6a900d3f662d1d3b6e2e59dcecf787b1cc3a1894",
|
||||
"sha256:a8bf8d0f749c5757af2142fe7903a9df1d2e8aa3841559b2bad34b08d0e2bcf3",
|
||||
"sha256:a9768c477b9d7bd54bc0c86dbaebdec6f03306675526c9927c0e8a04e8f94af9",
|
||||
"sha256:ac1c4a689edcc530fc9d9aa11f5774b9e2f33f9a0c6a57864e90908f5208d30a",
|
||||
"sha256:af2d8c67d8e573d6de5bc30cdb27e9b95e49115cd9baad5ddbd1a6207aaa82a9",
|
||||
"sha256:b435cba5f4f750aa6c0a0d92c541fb79f69a387c91e61f1795227e4ed9cece14",
|
||||
"sha256:b5b290ccc2a263e8d185130284f8501e3e36c5e02750fc6b6bdeb2e9e96f1e25",
|
||||
"sha256:b5d84d37db046c5ca74ee7bb47dd6cbc13f80665fdde3e8040bdd3fb015ecb50",
|
||||
"sha256:b7cf1017d601aa35e6bb650b6ad28652c9cd78ee6caff19f3c28d03e1c80acbf",
|
||||
"sha256:bc7637e2f80d8530ee4a78e878bce464f70087ce73cf7c1caf142416923b98f1",
|
||||
"sha256:c0463276121fdee9c49b98908b3a89c39be45d86d1dbaa22957e38f6321d4ce3",
|
||||
"sha256:c4ef880e27901b6cc782f1b95f82da9313c0eb95c3af699103088fa0ac3ce9ac",
|
||||
"sha256:c8ae8a0f02f57a6e61203a31428fa1d677cbe50c93622b4149d5c0f319c1d19e",
|
||||
"sha256:ca5862d5b3928c4940729dacc329aa9102900382fea192fc5e52eb69d6093815",
|
||||
"sha256:cb01158d8b88ee68f15949894ccc6712278243d95f344770fa7593fa2d94410c",
|
||||
"sha256:cb6254dc36b47a990e59e1068afacdcd02958bdcce30bb50cc1700a8b9d624a6",
|
||||
"sha256:cc00f04ed596e9dc0da42ed17ac5e596c6ccba999ba6bd92b0e0aef2f170f2d6",
|
||||
"sha256:cd09d08005f958f370f539f186d10aec3377d55b9eeb0d796025d4886119d76e",
|
||||
"sha256:cd4b7ca9984e5e7985c12bc60a6f173f3c958eae74f3ef6624bb6b26e2abbae4",
|
||||
"sha256:ce8a0633f41a967713a59c4139d29110c07e826d131a316b50ce11b1d79b4f84",
|
||||
"sha256:cead0978fc57397645f12578bfd2d5ea9138ea0fac82b2f63f7f7c6877986a69",
|
||||
"sha256:d055ec1e26e441f6187acf818b73564e6e6282709e9bcb5b63f5b23068356a15",
|
||||
"sha256:d1f13550535ad8cff21b8d757a3257963e951d96e20ec82ab44bc64aeb62a191",
|
||||
"sha256:d9c7f57c3d666a53421049053eaacdd14bbd0a528e2186fcb2e672effd053bb0",
|
||||
"sha256:d9e45d7faa48ee908174d8fe84854479ef838fc6a705c9315372eacbc2f02897",
|
||||
"sha256:da3326d9e65ef63a817ecbcc0df6e94463713b754fe293eaa03da99befb9a5bd",
|
||||
"sha256:de00632ca48df9daf77a2c65a484531649261ec9f25489917f09e455cb09ddb2",
|
||||
"sha256:e1f185f86a6f3403aa2420e815904c67b2f9ebc443f045edd0de921108345794",
|
||||
"sha256:e824f1492727fa856dd6eda4f7cee25f8518a12f3c4a56a74e8095695089cf6d",
|
||||
"sha256:e912091979546adf63357d7e2ccff9b44f026c075aeaf25a52d0e95ad2281074",
|
||||
"sha256:eaabd426fe94daf8fd157c32e571c85cb12e66692f15516a83a03264b08d06c3",
|
||||
"sha256:ebf3e58c7ec8a8bed6d66a75d7fb37b55e5015b03ceae72a8e7c74495551e224",
|
||||
"sha256:ecaae4149d99b1c9e7b88bb03e3221956f68fd6d50be2ef061b2381b61d20838",
|
||||
"sha256:eecbc200c7fd5ddb9a7f16c7decb07b566c29fa2161a16cf67b8d068bd21690a",
|
||||
"sha256:f155a433c2ec037d4e8df17d18922c3a0d9b3232a396690f17175d2946f0218d",
|
||||
"sha256:f1e34719c6ed0b92f418c7c780480b26b5d9c50349e9a9af7d76bf757530350d",
|
||||
"sha256:f34be2938726fc13801220747472850852fe6b1ea75869a048d6f896838c896f",
|
||||
"sha256:f820802628d2694cb7e56db99213f930856014862f3fd943d290ea8438d07ca8",
|
||||
"sha256:f8bf04158c6b607d747e93949aa60618b61312fe647a6369f88ce2ff16043490",
|
||||
"sha256:f8e160feb2aed042cd657a72acc0b481212ed28b1b9a95c0cee1621b524e1966",
|
||||
"sha256:f9d332f8c2a2fcbffe1378594431458ddbef721c1769d78e2cbc06280d8155f9",
|
||||
"sha256:fa09f53c465e532f4d3db095e0c55b615f010ad81803d383195b6b5ca6cbf5f3",
|
||||
"sha256:faa3a41b2b66b6e50f84ae4a68c64fcd0c44355741c6374813a800cd6695db9e",
|
||||
"sha256:fd44c878ea55ba351104cb93cc85e74916eb8fa440ca7903e57575e97394f608"
|
||||
],
|
||||
"markers": "python_version >= '3.7'",
|
||||
"version": "==3.4.4"
|
||||
},
|
||||
"docutils": {
|
||||
"hashes": [
|
||||
"sha256:4db53b1fde9abecbb74d91230d32ab626d94f6badfc575d6db9194a49df29968",
|
||||
"sha256:d0013f540772d1420576855455d050a2180186c91c15779301ac2ccb3eeb68de"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==0.22.4"
|
||||
},
|
||||
"idna": {
|
||||
"hashes": [
|
||||
"sha256:771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea",
|
||||
"sha256:795dafcc9c04ed0c1fb032c2aa73654d8e8c5023a7df64a53f39190ada629902"
|
||||
],
|
||||
"markers": "python_version >= '3.8'",
|
||||
"version": "==3.11"
|
||||
},
|
||||
"imagesize": {
|
||||
"hashes": [
|
||||
"sha256:0d8d18d08f840c19d0ee7ca1fd82490fdc3729b7ac93f49870406ddde8ef8d8b",
|
||||
"sha256:69150444affb9cb0d5cc5a92b3676f0b2fb7cd9ae39e947a5e11a36b4497cd4a"
|
||||
],
|
||||
"markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'",
|
||||
"version": "==1.4.1"
|
||||
},
|
||||
"jinja2": {
|
||||
"hashes": [
|
||||
"sha256:0137fb05990d35f1275a587e9aee6d56da821fc83491a0fb838183be43f66d6d",
|
||||
"sha256:85ece4451f492d0c13c5dd7c13a64681a86afae63a5f347908daf103ce6d2f67"
|
||||
],
|
||||
"markers": "python_version >= '3.7'",
|
||||
"version": "==3.1.6"
|
||||
},
|
||||
"markupsafe": {
|
||||
"hashes": [
|
||||
"sha256:0303439a41979d9e74d18ff5e2dd8c43ed6c6001fd40e5bf2e43f7bd9bbc523f",
|
||||
"sha256:068f375c472b3e7acbe2d5318dea141359e6900156b5b2ba06a30b169086b91a",
|
||||
"sha256:0bf2a864d67e76e5c9a34dc26ec616a66b9888e25e7b9460e1c76d3293bd9dbf",
|
||||
"sha256:0db14f5dafddbb6d9208827849fad01f1a2609380add406671a26386cdf15a19",
|
||||
"sha256:0eb9ff8191e8498cca014656ae6b8d61f39da5f95b488805da4bb029cccbfbaf",
|
||||
"sha256:0f4b68347f8c5eab4a13419215bdfd7f8c9b19f2b25520968adfad23eb0ce60c",
|
||||
"sha256:1085e7fbddd3be5f89cc898938f42c0b3c711fdcb37d75221de2666af647c175",
|
||||
"sha256:116bb52f642a37c115f517494ea5feb03889e04df47eeff5b130b1808ce7c219",
|
||||
"sha256:12c63dfb4a98206f045aa9563db46507995f7ef6d83b2f68eda65c307c6829eb",
|
||||
"sha256:133a43e73a802c5562be9bbcd03d090aa5a1fe899db609c29e8c8d815c5f6de6",
|
||||
"sha256:1353ef0c1b138e1907ae78e2f6c63ff67501122006b0f9abad68fda5f4ffc6ab",
|
||||
"sha256:15d939a21d546304880945ca1ecb8a039db6b4dc49b2c5a400387cdae6a62e26",
|
||||
"sha256:177b5253b2834fe3678cb4a5f0059808258584c559193998be2601324fdeafb1",
|
||||
"sha256:1872df69a4de6aead3491198eaf13810b565bdbeec3ae2dc8780f14458ec73ce",
|
||||
"sha256:1b4b79e8ebf6b55351f0d91fe80f893b4743f104bff22e90697db1590e47a218",
|
||||
"sha256:1b52b4fb9df4eb9ae465f8d0c228a00624de2334f216f178a995ccdcf82c4634",
|
||||
"sha256:1ba88449deb3de88bd40044603fafffb7bc2b055d626a330323a9ed736661695",
|
||||
"sha256:1cc7ea17a6824959616c525620e387f6dd30fec8cb44f649e31712db02123dad",
|
||||
"sha256:218551f6df4868a8d527e3062d0fb968682fe92054e89978594c28e642c43a73",
|
||||
"sha256:26a5784ded40c9e318cfc2bdb30fe164bdb8665ded9cd64d500a34fb42067b1c",
|
||||
"sha256:2713baf880df847f2bece4230d4d094280f4e67b1e813eec43b4c0e144a34ffe",
|
||||
"sha256:2a15a08b17dd94c53a1da0438822d70ebcd13f8c3a95abe3a9ef9f11a94830aa",
|
||||
"sha256:2f981d352f04553a7171b8e44369f2af4055f888dfb147d55e42d29e29e74559",
|
||||
"sha256:32001d6a8fc98c8cb5c947787c5d08b0a50663d139f1305bac5885d98d9b40fa",
|
||||
"sha256:3524b778fe5cfb3452a09d31e7b5adefeea8c5be1d43c4f810ba09f2ceb29d37",
|
||||
"sha256:3537e01efc9d4dccdf77221fb1cb3b8e1a38d5428920e0657ce299b20324d758",
|
||||
"sha256:35add3b638a5d900e807944a078b51922212fb3dedb01633a8defc4b01a3c85f",
|
||||
"sha256:38664109c14ffc9e7437e86b4dceb442b0096dfe3541d7864d9cbe1da4cf36c8",
|
||||
"sha256:3a7e8ae81ae39e62a41ec302f972ba6ae23a5c5396c8e60113e9066ef893da0d",
|
||||
"sha256:3b562dd9e9ea93f13d53989d23a7e775fdfd1066c33494ff43f5418bc8c58a5c",
|
||||
"sha256:457a69a9577064c05a97c41f4e65148652db078a3a509039e64d3467b9e7ef97",
|
||||
"sha256:4bd4cd07944443f5a265608cc6aab442e4f74dff8088b0dfc8238647b8f6ae9a",
|
||||
"sha256:4e885a3d1efa2eadc93c894a21770e4bc67899e3543680313b09f139e149ab19",
|
||||
"sha256:4faffd047e07c38848ce017e8725090413cd80cbc23d86e55c587bf979e579c9",
|
||||
"sha256:509fa21c6deb7a7a273d629cf5ec029bc209d1a51178615ddf718f5918992ab9",
|
||||
"sha256:5678211cb9333a6468fb8d8be0305520aa073f50d17f089b5b4b477ea6e67fdc",
|
||||
"sha256:591ae9f2a647529ca990bc681daebdd52c8791ff06c2bfa05b65163e28102ef2",
|
||||
"sha256:5a7d5dc5140555cf21a6fefbdbf8723f06fcd2f63ef108f2854de715e4422cb4",
|
||||
"sha256:69c0b73548bc525c8cb9a251cddf1931d1db4d2258e9599c28c07ef3580ef354",
|
||||
"sha256:6b5420a1d9450023228968e7e6a9ce57f65d148ab56d2313fcd589eee96a7a50",
|
||||
"sha256:722695808f4b6457b320fdc131280796bdceb04ab50fe1795cd540799ebe1698",
|
||||
"sha256:729586769a26dbceff69f7a7dbbf59ab6572b99d94576a5592625d5b411576b9",
|
||||
"sha256:77f0643abe7495da77fb436f50f8dab76dbc6e5fd25d39589a0f1fe6548bfa2b",
|
||||
"sha256:795e7751525cae078558e679d646ae45574b47ed6e7771863fcc079a6171a0fc",
|
||||
"sha256:7be7b61bb172e1ed687f1754f8e7484f1c8019780f6f6b0786e76bb01c2ae115",
|
||||
"sha256:7c3fb7d25180895632e5d3148dbdc29ea38ccb7fd210aa27acbd1201a1902c6e",
|
||||
"sha256:7e68f88e5b8799aa49c85cd116c932a1ac15caaa3f5db09087854d218359e485",
|
||||
"sha256:83891d0e9fb81a825d9a6d61e3f07550ca70a076484292a70fde82c4b807286f",
|
||||
"sha256:8485f406a96febb5140bfeca44a73e3ce5116b2501ac54fe953e488fb1d03b12",
|
||||
"sha256:8709b08f4a89aa7586de0aadc8da56180242ee0ada3999749b183aa23df95025",
|
||||
"sha256:8f71bc33915be5186016f675cd83a1e08523649b0e33efdb898db577ef5bb009",
|
||||
"sha256:915c04ba3851909ce68ccc2b8e2cd691618c4dc4c4232fb7982bca3f41fd8c3d",
|
||||
"sha256:949b8d66bc381ee8b007cd945914c721d9aba8e27f71959d750a46f7c282b20b",
|
||||
"sha256:94c6f0bb423f739146aec64595853541634bde58b2135f27f61c1ffd1cd4d16a",
|
||||
"sha256:9a1abfdc021a164803f4d485104931fb8f8c1efd55bc6b748d2f5774e78b62c5",
|
||||
"sha256:9b79b7a16f7fedff2495d684f2b59b0457c3b493778c9eed31111be64d58279f",
|
||||
"sha256:a320721ab5a1aba0a233739394eb907f8c8da5c98c9181d1161e77a0c8e36f2d",
|
||||
"sha256:a4afe79fb3de0b7097d81da19090f4df4f8d3a2b3adaa8764138aac2e44f3af1",
|
||||
"sha256:ad2cf8aa28b8c020ab2fc8287b0f823d0a7d8630784c31e9ee5edea20f406287",
|
||||
"sha256:b8512a91625c9b3da6f127803b166b629725e68af71f8184ae7e7d54686a56d6",
|
||||
"sha256:bc51efed119bc9cfdf792cdeaa4d67e8f6fcccab66ed4bfdd6bde3e59bfcbb2f",
|
||||
"sha256:bdc919ead48f234740ad807933cdf545180bfbe9342c2bb451556db2ed958581",
|
||||
"sha256:bdd37121970bfd8be76c5fb069c7751683bdf373db1ed6c010162b2a130248ed",
|
||||
"sha256:be8813b57049a7dc738189df53d69395eba14fb99345e0a5994914a3864c8a4b",
|
||||
"sha256:c0c0b3ade1c0b13b936d7970b1d37a57acde9199dc2aecc4c336773e1d86049c",
|
||||
"sha256:c47a551199eb8eb2121d4f0f15ae0f923d31350ab9280078d1e5f12b249e0026",
|
||||
"sha256:c4ffb7ebf07cfe8931028e3e4c85f0357459a3f9f9490886198848f4fa002ec8",
|
||||
"sha256:ccfcd093f13f0f0b7fdd0f198b90053bf7b2f02a3927a30e63f3ccc9df56b676",
|
||||
"sha256:d2ee202e79d8ed691ceebae8e0486bd9a2cd4794cec4824e1c99b6f5009502f6",
|
||||
"sha256:d53197da72cc091b024dd97249dfc7794d6a56530370992a5e1a08983ad9230e",
|
||||
"sha256:d6dd0be5b5b189d31db7cda48b91d7e0a9795f31430b7f271219ab30f1d3ac9d",
|
||||
"sha256:d88b440e37a16e651bda4c7c2b930eb586fd15ca7406cb39e211fcff3bf3017d",
|
||||
"sha256:de8a88e63464af587c950061a5e6a67d3632e36df62b986892331d4620a35c01",
|
||||
"sha256:df2449253ef108a379b8b5d6b43f4b1a8e81a061d6537becd5582fba5f9196d7",
|
||||
"sha256:e1c1493fb6e50ab01d20a22826e57520f1284df32f2d8601fdd90b6304601419",
|
||||
"sha256:e1cf1972137e83c5d4c136c43ced9ac51d0e124706ee1c8aa8532c1287fa8795",
|
||||
"sha256:e2103a929dfa2fcaf9bb4e7c091983a49c9ac3b19c9061b6d5427dd7d14d81a1",
|
||||
"sha256:e56b7d45a839a697b5eb268c82a71bd8c7f6c94d6fd50c3d577fa39a9f1409f5",
|
||||
"sha256:e8afc3f2ccfa24215f8cb28dcf43f0113ac3c37c2f0f0806d8c70e4228c5cf4d",
|
||||
"sha256:e8fc20152abba6b83724d7ff268c249fa196d8259ff481f3b1476383f8f24e42",
|
||||
"sha256:eaa9599de571d72e2daf60164784109f19978b327a3910d3e9de8c97b5b70cfe",
|
||||
"sha256:ec15a59cf5af7be74194f7ab02d0f59a62bdcf1a537677ce67a2537c9b87fcda",
|
||||
"sha256:f190daf01f13c72eac4efd5c430a8de82489d9cff23c364c3ea822545032993e",
|
||||
"sha256:f34c41761022dd093b4b6896d4810782ffbabe30f2d443ff5f083e0cbbb8c737",
|
||||
"sha256:f3e98bb3798ead92273dc0e5fd0f31ade220f59a266ffd8a4f6065e0a3ce0523",
|
||||
"sha256:f42d0984e947b8adf7dd6dde396e720934d12c506ce84eea8476409563607591",
|
||||
"sha256:f71a396b3bf33ecaa1626c255855702aca4d3d9fea5e051b41ac59a9c1c41edc",
|
||||
"sha256:f9e130248f4462aaa8e2552d547f36ddadbeaa573879158d721bbd33dfe4743a",
|
||||
"sha256:fed51ac40f757d41b7c48425901843666a6677e3e8eb0abcff09e4ba6e664f50"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==3.0.3"
|
||||
},
|
||||
"packaging": {
|
||||
"hashes": [
|
||||
"sha256:00243ae351a257117b6a241061796684b084ed1c516a08c48a3f7e147a9d80b4",
|
||||
"sha256:b36f1fef9334a5588b4166f8bcd26a14e521f2b55e6b9de3aaa80d3ff7a37529"
|
||||
],
|
||||
"markers": "python_version >= '3.8'",
|
||||
"version": "==26.0"
|
||||
},
|
||||
"pygments": {
|
||||
"hashes": [
|
||||
"sha256:636cb2477cec7f8952536970bc533bc43743542f70392ae026374600add5b887",
|
||||
"sha256:86540386c03d588bb81d44bc3928634ff26449851e99741617ecb9037ee5ec0b"
|
||||
],
|
||||
"markers": "python_version >= '3.8'",
|
||||
"version": "==2.19.2"
|
||||
},
|
||||
"requests": {
|
||||
"hashes": [
|
||||
"sha256:2462f94637a34fd532264295e186976db0f5d453d1cdd31473c85a6a161affb6",
|
||||
"sha256:dbba0bac56e100853db0ea71b82b4dfd5fe2bf6d3754a8893c3af500cec7d7cf"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==2.32.5"
|
||||
},
|
||||
"roman-numerals": {
|
||||
"hashes": [
|
||||
"sha256:1af8b147eb1405d5839e78aeb93131690495fe9da5c91856cb33ad55a7f1e5b2",
|
||||
"sha256:647ba99caddc2cc1e55a51e4360689115551bf4476d90e8162cf8c345fe233c7"
|
||||
],
|
||||
"markers": "python_version >= '3.10'",
|
||||
"version": "==4.1.0"
|
||||
},
|
||||
"snowballstemmer": {
|
||||
"hashes": [
|
||||
"sha256:6cd7b3897da8d6c9ffb968a6781fa6532dce9c3618a4b127d920dab764a19064",
|
||||
"sha256:6d5eeeec8e9f84d4d56b847692bacf79bc2c8e90c7f80ca4444ff8b6f2e52895"
|
||||
],
|
||||
"markers": "python_version not in '3.0, 3.1, 3.2'",
|
||||
"version": "==3.0.1"
|
||||
},
|
||||
"sphinx": {
|
||||
"hashes": [
|
||||
"sha256:7741722357dd75f8190766926071fed3bdc211c74dd2d7d4df5404da95930ddb",
|
||||
"sha256:c84fdd4e782504495fe4f2c0b3413d6c2bf388589bb352d439b2a3bb99991978"
|
||||
],
|
||||
"index": "pypi",
|
||||
"markers": "python_version >= '3.12'",
|
||||
"version": "==9.1.0"
|
||||
},
|
||||
"sphinx-last-updated-by-git": {
|
||||
"hashes": [
|
||||
"sha256:6382c8285ac1f222483a58569b78c0371af5e55f7fbf9c01e5e8a72d6fdfa499",
|
||||
"sha256:c145011f4609d841805b69a9300099fc02fed8f5bb9e5bcef77d97aea97b7761"
|
||||
],
|
||||
"index": "pypi",
|
||||
"markers": "python_version >= '3.7'",
|
||||
"version": "==0.3.8"
|
||||
},
|
||||
"sphinx-markdown-builder": {
|
||||
"hashes": [
|
||||
"sha256:35b555760c48d4a38fe4b27813cb5ca636bbd22d8ef0742ac6959043f8000840",
|
||||
"sha256:e89dc1b9eb837da430c2c230011fad95a3dfab0345ad503a32e35a31d284a722"
|
||||
],
|
||||
"index": "pypi",
|
||||
"markers": "python_version >= '3.7'",
|
||||
"version": "==0.6.9"
|
||||
},
|
||||
"sphinxcontrib-applehelp": {
|
||||
"hashes": [
|
||||
"sha256:2f29ef331735ce958efa4734873f084941970894c6090408b079c61b2e1c06d1",
|
||||
"sha256:4cd3f0ec4ac5dd9c17ec65e9ab272c9b867ea77425228e68ecf08d6b28ddbdb5"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==2.0.0"
|
||||
},
|
||||
"sphinxcontrib-devhelp": {
|
||||
"hashes": [
|
||||
"sha256:411f5d96d445d1d73bb5d52133377b4248ec79db5c793ce7dbe59e074b4dd1ad",
|
||||
"sha256:aefb8b83854e4b0998877524d1029fd3e6879210422ee3780459e28a1f03a8a2"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==2.0.0"
|
||||
},
|
||||
"sphinxcontrib-htmlhelp": {
|
||||
"hashes": [
|
||||
"sha256:166759820b47002d22914d64a075ce08f4c46818e17cfc9470a9786b759b19f8",
|
||||
"sha256:c9e2916ace8aad64cc13a0d233ee22317f2b9025b9cf3295249fa985cc7082e9"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==2.1.0"
|
||||
},
|
||||
"sphinxcontrib-jsmath": {
|
||||
"hashes": [
|
||||
"sha256:2ec2eaebfb78f3f2078e73666b1415417a116cc848b72e5172e596c871103178",
|
||||
"sha256:a9925e4a4587247ed2191a22df5f6970656cb8ca2bd6284309578f2153e0c4b8"
|
||||
],
|
||||
"markers": "python_version >= '3.5'",
|
||||
"version": "==1.0.1"
|
||||
},
|
||||
"sphinxcontrib-qthelp": {
|
||||
"hashes": [
|
||||
"sha256:4fe7d0ac8fc171045be623aba3e2a8f613f8682731f9153bb2e40ece16b9bbab",
|
||||
"sha256:b18a828cdba941ccd6ee8445dbe72ffa3ef8cbe7505d8cd1fa0d42d3f2d5f3eb"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==2.0.0"
|
||||
},
|
||||
"sphinxcontrib-serializinghtml": {
|
||||
"hashes": [
|
||||
"sha256:6e2cb0eef194e10c27ec0023bfeb25badbbb5868244cf5bc5bdc04e4464bf331",
|
||||
"sha256:e9d912827f872c029017a53f0ef2180b327c3f7fd23c87229f7a8e8b70031d4d"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==2.0.0"
|
||||
},
|
||||
"tabulate": {
|
||||
"hashes": [
|
||||
"sha256:0095b12bf5966de529c0feb1fa08671671b3368eec77d7ef7ab114be2c068b3c",
|
||||
"sha256:024ca478df22e9340661486f85298cff5f6dcdba14f3813e8830015b9ed1948f"
|
||||
],
|
||||
"markers": "python_version >= '3.7'",
|
||||
"version": "==0.9.0"
|
||||
},
|
||||
"urllib3": {
|
||||
"hashes": [
|
||||
"sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed",
|
||||
"sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4"
|
||||
],
|
||||
"markers": "python_version >= '3.9'",
|
||||
"version": "==2.6.3"
|
||||
}
|
||||
},
|
||||
"develop": {}
|
||||
}
|
||||
1
dist/markdown
vendored
Submodule
1
dist/markdown
vendored
Submodule
|
|
@ -0,0 +1 @@
|
|||
Subproject commit 41481636d866a24c7d1d55d13310cd45dacf6494
|
||||
1
src/.gitignore
vendored
Normal file
1
src/.gitignore
vendored
Normal file
|
|
@ -0,0 +1 @@
|
|||
/.doctrees/
|
||||
198
src/AGENTS.rst
Normal file
198
src/AGENTS.rst
Normal file
|
|
@ -0,0 +1,198 @@
|
|||
######
|
||||
AGENTS
|
||||
######
|
||||
|
||||
Operational Guidance for Autonomous Agents Using specification (ABC Specification)
|
||||
==================================================================================
|
||||
|
||||
MUST USE ``index.md`` as entrypoint for specification and subsequent referenced
|
||||
documents within.
|
||||
|
||||
Purpose of this document
|
||||
------------------------
|
||||
|
||||
This document defines how an autonomous agent must operate when using the
|
||||
Abstract Base Cloud (ABC) Specification (specification) as the authoritative
|
||||
source of truth. It does not redefine, summarize, or restate the ABC Pattern.
|
||||
Its purpose is to establish procedures, behaviors, and decision rules that
|
||||
ensure all agent actions remain compliant with the specification.
|
||||
|
||||
How to Read and Interpret spec.txt
|
||||
----------------------------------
|
||||
|
||||
#. Treat specification as canonical; all definitions, rules, and schemas
|
||||
originate there.
|
||||
#. When encountering ambiguity, defer to specification rather than internal
|
||||
heuristics.
|
||||
#. When interpreting any rule:
|
||||
- Use the identifiers in specification as binding references.
|
||||
- Do not reinterpret or rephrase the rule; apply it operationally.
|
||||
#. When a task requires clarification, locate the relevant section in
|
||||
specification and apply its constraints directly.
|
||||
|
||||
How to Apply the ABC Normative Rules
|
||||
------------------------------------
|
||||
|
||||
#. Use normative rules as constraints on generation and transformation.
|
||||
#. For any action:
|
||||
- Identify which normative rules apply.
|
||||
- Enforce them mechanically.
|
||||
#. When generating constructs:
|
||||
- Ensure hierarchy, relationships, interfaces, and data flow conform to
|
||||
normative rules.
|
||||
#. When routing data:
|
||||
- Apply downward and upward flow rules exactly as defined.
|
||||
#. When evaluating a user request:
|
||||
- Reject or correct requests that would violate normative rules.
|
||||
|
||||
|
||||
How to Apply the ABC Validation Rules
|
||||
-------------------------------------
|
||||
#. Treat validation rules as mechanical checks.
|
||||
#. For any ABC architecture:
|
||||
- Validate structure.
|
||||
- Validate contracts.
|
||||
- Validate data flow.
|
||||
- Validate instantiation semantics.
|
||||
#. When a violation is detected:
|
||||
- Identify the violated rule by its identifier.
|
||||
- Provide a corrective action path.
|
||||
#. Never modify validation rules; only apply them.
|
||||
|
||||
|
||||
SECTION 5 — How to Use the ABC Schema
|
||||
-------------------------------------
|
||||
#. Use the schema as the machine-readable representation of an ABC architecture.
|
||||
#. When generating or transforming architectures:
|
||||
- Produce JSON that conforms exactly to the schema.
|
||||
#. When validating:
|
||||
- Apply schema constraints before normative or validation rules.
|
||||
#. When consuming the schema:
|
||||
- Use ``$defs`` to resolve construct types, contracts, and rule bindings.
|
||||
#. Never alter the schema; only instantiate or validate against it.
|
||||
|
||||
How to Use the Code Generation Profiles
|
||||
---------------------------------------
|
||||
|
||||
#. Profiles define how to map ABC constructs into specific IaC tools.
|
||||
#. When generating code:
|
||||
- Select the appropriate profile.
|
||||
- Apply profile rules exactly as written in specification.
|
||||
#. When a profile conflicts with user instructions:
|
||||
- The profile takes precedence.
|
||||
#. When generating code:
|
||||
- Use the ABC hierarchy as the structural backbone.
|
||||
- Use Input/Output Contracts as the only wiring mechanism.
|
||||
#. Never invent new profile rules; only apply those defined in specification.
|
||||
|
||||
Operational Procedures for Construct Creation
|
||||
---------------------------------------------
|
||||
|
||||
#. Determine the construct type.
|
||||
#. Create the construct with:
|
||||
- A unique ID.
|
||||
- A valid parent (except ApplicationStack).
|
||||
- A complete Input Contract.
|
||||
- A complete Output Contract.
|
||||
#. Instantiate children strictly top-down.
|
||||
#. Ensure no lateral references are introduced.
|
||||
#. Enforce immutability of Input Contracts.
|
||||
|
||||
Operational Procedures for Data Flow Wiring
|
||||
-------------------------------------------
|
||||
|
||||
#. For downward flow:
|
||||
- Pass only the required subset of parent inputs/outputs.
|
||||
- Ensure all downward values originate from the parent’s declared contracts.
|
||||
#. For upward flow:
|
||||
- Expose only declared outputs.
|
||||
- Aggregate or transform outputs only at the parent level.
|
||||
#. Never allow:
|
||||
- Sibling-to-sibling communication.
|
||||
- Access to undeclared values.
|
||||
- Implicit or hidden data flow.
|
||||
|
||||
Operational Procedures for Validation
|
||||
-------------------------------------
|
||||
|
||||
#. Validate in this order:
|
||||
- Schema conformance.
|
||||
- Structural validation rules.
|
||||
- Contract validation rules.
|
||||
- Data-flow validation rules.
|
||||
- Instantiation validation rules.
|
||||
#. For each violation:
|
||||
- Identify the rule ID.
|
||||
- Provide a deterministic correction path.
|
||||
#. Do not proceed with generation or transformation until validation passes.
|
||||
|
||||
Operational Procedures for Refactoring
|
||||
--------------------------------------
|
||||
|
||||
#. Load the existing architecture from its schema representation.
|
||||
#. Identify the target change.
|
||||
#. Determine which constructs, contracts, or data flows are affected.
|
||||
#. Apply changes while enforcing:
|
||||
- Contract stability requirements.
|
||||
- Parent–child mediation rules.
|
||||
- No lateral references.
|
||||
#. After refactoring:
|
||||
- Revalidate the entire architecture.
|
||||
- Ensure all rule identifiers remain satisfied.
|
||||
|
||||
Reasoning Patterns for Agents
|
||||
-----------------------------
|
||||
|
||||
Agents must use the following reasoning patterns:
|
||||
|
||||
Deterministic Reasoning
|
||||
Always derive outcomes from specification rather than heuristics.
|
||||
|
||||
Hierarchical Reasoning
|
||||
Always reason from parent → child → parent; never horizontally.
|
||||
|
||||
Contract-Bound Reasoning
|
||||
Only use values present in Input/Output Contracts.
|
||||
|
||||
Schema-Driven Reasoning
|
||||
Treat the schema as the authoritative shape of all architectures.
|
||||
|
||||
Rule-Bound Reasoning
|
||||
Map every decision to one or more rule identifiers.
|
||||
|
||||
|
||||
Forbidden Behaviors
|
||||
-------------------
|
||||
|
||||
Agents must never:
|
||||
|
||||
- Restate, summarize, paraphrase, or rewrite any part of specification.
|
||||
- Invent new ABC rules or modify existing ones.
|
||||
- Introduce lateral references between constructs.
|
||||
- Generate architectures that violate any rule in specification.
|
||||
- Infer missing contract fields not explicitly provided.
|
||||
- Create implicit dependencies or hidden data flow.
|
||||
- Generate code that does not follow the selected profile.
|
||||
- Produce constructs outside the allowed hierarchy.
|
||||
- Mutate Input Contracts after instantiation.
|
||||
- Expose values not declared in Output Contracts.
|
||||
|
||||
|
||||
Agent Behavioral Contract
|
||||
-------------------------
|
||||
|
||||
Agents must:
|
||||
|
||||
#. Treat specification as the single source of truth.
|
||||
#. Apply rules without reinterpretation.
|
||||
#. Produce deterministic, reproducible outputs.
|
||||
#. Validate all generated artifacts before returning them.
|
||||
#. Reject or correct user requests that violate the specification.
|
||||
#. Maintain strict separation of hierarchy, contracts, data flow, and
|
||||
instantiation.
|
||||
#. Ensure all transformations preserve rule compliance.
|
||||
#. Use profile mappings exactly as defined.
|
||||
#. Operate without assumptions, guesses, or implicit dependencies.
|
||||
#. Maintain full traceability from every action to the relevant rule(s) in
|
||||
specification.
|
||||
|
||||
78
src/concepts.rst
Normal file
78
src/concepts.rst
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
########
|
||||
Concepts
|
||||
########
|
||||
|
||||
ABC-C0 - Construct
|
||||
==================
|
||||
|
||||
An encapsulated unit of infrastructure logic that can represent an Application
|
||||
Stack, Logical Unit, Resource Group, or any reusable component. It exposes a
|
||||
single Instantiation Interface and implements its behavior internally,
|
||||
independent of other constructs.
|
||||
|
||||
ABC-C1 - Application Stack
|
||||
==========================
|
||||
|
||||
The top‑level construct representing the entire deployment boundary of an
|
||||
application. It composes multiple Logical Units, orchestrates their
|
||||
instantiation, and mediates all data flow between them. It exposes a single,
|
||||
coherent input/output surface for the whole system.
|
||||
|
||||
ABC-C2 - Logical Unit
|
||||
=====================
|
||||
|
||||
A first‑level subdivision within the Application Stack that encapsulates a major
|
||||
functional domain (e.g., Data, Logic, Presentation). It contains one or more
|
||||
Resource Groups and defines explicit input/output contracts for interaction with
|
||||
the Application Stack.
|
||||
|
||||
ABC-C3 - Resource Group
|
||||
=======================
|
||||
|
||||
A fine‑grained construct within a Logical Unit that provisions a cohesive set of
|
||||
related resources. It receives only the inputs it requires from its parent
|
||||
Logical Unit and returns outputs upward; it never communicates directly with
|
||||
sibling Resource Groups.
|
||||
|
||||
ABC-C4 - Input Contract
|
||||
=======================
|
||||
|
||||
A formally defined set of parameters that a Construct (ABC‑C0) MUST receive from
|
||||
its parent. It specifies all required configuration, contextual values, and
|
||||
dependencies needed for correct instantiation. It prohibits implicit or global
|
||||
state; every dependency must appear explicitly in this contract.
|
||||
|
||||
ABC-C5 - Output Contract
|
||||
========================
|
||||
|
||||
A formally defined set of values that a Construct (ABC‑C0) MUST expose upward to
|
||||
its parent. It represents the complete set of externally consumable identifiers,
|
||||
endpoints, or computed values produced by the construct. It ensures that all
|
||||
upward dependencies are explicit and traceable.
|
||||
|
||||
ABC-C6 - Instantiation Interface
|
||||
================================
|
||||
|
||||
The single, explicit mechanism through which a Construct (ABC‑C0) is created and
|
||||
provided with its Input Contract (ABC‑C4). It defines how callers supply inputs
|
||||
and how the construct exposes its Output Contract (ABC‑C5). The interface is
|
||||
stable, minimal, and framework‑agnostic, ensuring that internal implementation
|
||||
details never leak into parent constructs.
|
||||
|
||||
ABC-C7 - Capturing Down
|
||||
=======================
|
||||
|
||||
A parent‑to‑child data‑flow mechanism in which a Construct (ABC‑C0) provides its
|
||||
children with the exact subset of inputs they require. It ensures that all
|
||||
downward dependencies are explicit, scoped, and passed only through the child’s
|
||||
Input Contract (ABC‑C4). No child may access parent state except through this
|
||||
mechanism.
|
||||
|
||||
ABC-C8 - Bubbling Up
|
||||
====================
|
||||
|
||||
A child‑to‑parent data‑flow mechanism in which a Construct (ABC‑C0) exposes its
|
||||
outputs exclusively through its Output Contract (ABC‑C5). Parents receive these
|
||||
outputs, may aggregate or transform them, and may optionally pass them further
|
||||
down to other children via Capturing Down. No lateral or implicit communication
|
||||
is permitted.
|
||||
41
src/conf.py
Normal file
41
src/conf.py
Normal file
|
|
@ -0,0 +1,41 @@
|
|||
import datetime
|
||||
|
||||
extensions = [
|
||||
'sphinx.ext.intersphinx',
|
||||
'sphinx.ext.todo',
|
||||
'sphinx_last_updated_by_git',
|
||||
'sphinx_markdown_builder'
|
||||
]
|
||||
|
||||
|
||||
templates_path = ["_templates"]
|
||||
|
||||
project = "Abstract Base Cloud Specification"
|
||||
copyright = "2026, Tiara Rodney"
|
||||
|
||||
html_title = project
|
||||
html_theme = 'pydata_sphinx_theme'
|
||||
html_sidebars = {}
|
||||
html_show_sphinx = False
|
||||
html_show_sourcelink = False
|
||||
|
||||
html_context = {
|
||||
"bitbucket_url": "https://bitbucket.org",
|
||||
"bitbucket_user": "byteb4rb1e",
|
||||
"bitbucket_repo": "blog.tiararodney.com",
|
||||
"bitbucket_version": "master",
|
||||
"doc_path": "src/"
|
||||
}
|
||||
|
||||
|
||||
|
||||
language = 'en'
|
||||
|
||||
todo_include_todos = True
|
||||
|
||||
rst_prolog = f"""
|
||||
.. |build-time| replace:: {datetime.datetime.now().strftime("%d %B %Y, %H:%M")}
|
||||
"""
|
||||
|
||||
html_last_updated_fmt = "%d %B %Y, %H:%M"
|
||||
|
||||
386
src/example.rst
Normal file
386
src/example.rst
Normal file
|
|
@ -0,0 +1,386 @@
|
|||
#################
|
||||
Canonical Example
|
||||
#################
|
||||
|
||||
This example demonstrates how the ABC Pattern structures a real application
|
||||
using only:
|
||||
|
||||
* Constructs (ABC‑C0)
|
||||
* Application Stack (ABC‑C1)
|
||||
* Logical Units (ABC‑C2)
|
||||
* Resource Groups (ABC‑C3)
|
||||
* Input/Output Contracts (ABC‑C4, ABC‑C5)
|
||||
* Instantiation Interface (ABC‑C6)
|
||||
* Capturing Down (ABC‑C7)
|
||||
* Bubbling Up (ABC‑C8)
|
||||
|
||||
Every interaction is explicit. Every dependency is visible. Nothing leaks
|
||||
sideways.
|
||||
|
||||
Overview
|
||||
========
|
||||
|
||||
We model a classic 3‑tier architecture:
|
||||
|
||||
* Data Tier - database + storage
|
||||
* Logic Tier - compute + messaging
|
||||
* Presentation Tier - CDN + web frontend
|
||||
|
||||
Each tier is a Logical Unit (ABC‑C2).
|
||||
|
||||
Each component inside a tier is a Resource Group (ABC‑C3).
|
||||
|
||||
The Application Stack (ABC‑C1) composes them, wires them, and exposes the final
|
||||
outputs.
|
||||
|
||||
Conceptual Diagram
|
||||
==================
|
||||
|
||||
.. code-block::
|
||||
|
||||
┌──────────────────────────────┐
|
||||
│ Application Stack │
|
||||
│ (ABC‑C1) │
|
||||
└─────────────┬────────────────┘
|
||||
│
|
||||
┌──────────────────────┼────────────────────────┐
|
||||
│ │ │
|
||||
┌───────▼────────┐ ┌───────▼────────┐ ┌─────────▼────────┐
|
||||
│ DataUnit │ │ LogicUnit │ │ PresentationUnit │
|
||||
│ (C2) │ │ (C2) │ │ (C2) │
|
||||
└───────┬────────┘ └───────┬────────┘ └────────┬─────────┘
|
||||
│ │ │
|
||||
│ │ ┌────────│──────┐
|
||||
┌────▼─────┐ ┌────▼─────┐ ┌────▼──────┐ ┌──────▼─────┐
|
||||
│StorageGrp│ │ComputeGrp│ │WebAppGrp │ │ CDNGrp │
|
||||
│ (C3) │ │ (C3) │ │ (C3) │ │ (C3) │
|
||||
└──────────┘ └──────────┘ └───────────┘ └────────────┘
|
||||
|
||||
Application Stack (ABC‑C1)
|
||||
==========================
|
||||
|
||||
The Application Stack is the root construct.
|
||||
|
||||
It has no parent and defines the deployment boundary.
|
||||
|
||||
Responsibilities
|
||||
----------------
|
||||
|
||||
* Instantiate each Logical Unit (ABC‑R1).
|
||||
* Provide downward inputs (ABC‑F1).
|
||||
* Receive upward outputs (ABC‑F2).
|
||||
* Route outputs between Logical Units (ABC‑R44).
|
||||
* Expose a final Output Contract representing the whole system.
|
||||
|
||||
Input Contract (ABC‑C4)
|
||||
-----------------------
|
||||
|
||||
The Application Stack receives only global configuration:
|
||||
|
||||
.. code-block::
|
||||
|
||||
AppStackInputs:
|
||||
environment: string
|
||||
region: string
|
||||
global_tags: map<string,string>
|
||||
|
||||
Output Contract (ABC‑C5)
|
||||
------------------------
|
||||
|
||||
The Application Stack exposes:
|
||||
|
||||
.. code-block::
|
||||
|
||||
AppStackOutputs:
|
||||
frontend_url: string
|
||||
api_endpoint: string
|
||||
|
||||
These values originate from the Presentation and Logic tiers, respectively.
|
||||
|
||||
Logical Units (ABC‑C2)
|
||||
======================
|
||||
|
||||
Each Logical Unit encapsulates a functional domain.
|
||||
|
||||
They do not know about each other.
|
||||
|
||||
They communicate only through the Application Stack.
|
||||
|
||||
We define three:
|
||||
|
||||
* DataUnit
|
||||
* LogicUnit
|
||||
* PresentationUnit
|
||||
|
||||
Each has its own Input/Output Contracts and internal Resource Groups.
|
||||
|
||||
Data Logical Unit (ABC‑C2)
|
||||
--------------------------
|
||||
|
||||
Purpose
|
||||
^^^^^^^
|
||||
|
||||
Provide persistent storage and database capabilities.
|
||||
|
||||
Resource Groups (ABC‑C3)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
* StorageGroup - object storage
|
||||
* DatabaseGroup - relational database
|
||||
|
||||
Input Contract
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
DataUnitInputs:
|
||||
environment: string
|
||||
region: string
|
||||
storage_class: string
|
||||
db_engine: string
|
||||
db_instance_size: string
|
||||
|
||||
Output Contract
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
DataUnitOutputs:
|
||||
storage_bucket_name: string
|
||||
database_endpoint: string
|
||||
|
||||
Internal Wiring
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
* StorageGroup produces ``storage_bucket_name``.
|
||||
* DatabaseGroup produces ``database_endpoint``.
|
||||
* DataUnit aggregates both and bubbles them up (ABC‑F2).
|
||||
|
||||
.. note::
|
||||
|
||||
* StorageGroup and DatabaseGroup do not know about each other (ABC‑R10).
|
||||
* All configuration flows downward from DataUnit (ABC‑F1).
|
||||
|
||||
Logic Logical Unit (ABC‑C2)
|
||||
---------------------------
|
||||
|
||||
Purpose
|
||||
^^^^^^^
|
||||
|
||||
Provide compute and messaging capabilities for the application backend.
|
||||
|
||||
Resource Groups
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
* ComputeGroup - application compute (e.g., functions, containers)
|
||||
* MessagingGroup - queue or pub/sub system
|
||||
|
||||
Input Contract
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
LogicUnitInputs:
|
||||
environment: string
|
||||
region: string
|
||||
compute_size: string
|
||||
message_retention: number
|
||||
database_endpoint: string # Provided by DataUnit via AppStack
|
||||
|
||||
Output Contract
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
LogicUnitOutputs:
|
||||
api_endpoint: string
|
||||
message_queue_url: string
|
||||
|
||||
Internal Wiring
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
* ComputeGroup receives ``database_endpoint`` via Capturing Down (ABC‑F1).
|
||||
* MessagingGroup is independent.
|
||||
* LogicUnit aggregates outputs and bubbles them up.
|
||||
|
||||
.. note::
|
||||
|
||||
* LogicUnit does not know where the database came from.
|
||||
* It only knows it received a database_endpoint in its Input Contract
|
||||
(ABC‑R22).
|
||||
|
||||
Presentation Logical Unit (ABC‑C2)
|
||||
----------------------------------
|
||||
|
||||
Purpose
|
||||
^^^^^^^
|
||||
|
||||
Serve the frontend and expose the public entry point.
|
||||
|
||||
Resource Groups
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
* CDNGroup - global content distribution
|
||||
* WebAppGroup - static or dynamic frontend
|
||||
|
||||
Input Contract
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
PresentationUnitInputs:
|
||||
environment: string
|
||||
region: string
|
||||
frontend_assets_bucket: string
|
||||
api_endpoint: string # Provided by LogicUnit via AppStack
|
||||
|
||||
Output Contract
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
PresentationUnitOutputs:
|
||||
frontend_url: string
|
||||
|
||||
Internal Wiring
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
* WebAppGroup receives ``api_endpoint`` via Capturing Down.
|
||||
* CDNGroup receives the output of WebAppGroup.
|
||||
* PresentationUnit bubbles up the final ``frontend_url``.
|
||||
|
||||
Resource Groups (ABC‑C3)
|
||||
========================
|
||||
|
||||
Each Resource Group is a small, focused construct with:
|
||||
|
||||
* A minimal Input Contract
|
||||
* A minimal Output Contract
|
||||
* No knowledge of siblings
|
||||
* No access to parent state except via inputs
|
||||
* No side effects during instantiation (ABC‑R33)
|
||||
|
||||
Example: Database Group
|
||||
-----------------------
|
||||
|
||||
Input Contract
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
DatabaseGroupInputs:
|
||||
db_engine: string
|
||||
db_instance_size: string
|
||||
environment: string
|
||||
|
||||
Output Contract
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
DatabaseGroupOutputs:
|
||||
database_endpoint: string
|
||||
|
||||
Instantiation Interface
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
|
||||
new DatabaseGroup(DatabaseGroupInputs) -> DatabaseGroupOutputs
|
||||
|
||||
This pattern repeats for all Resource Groups.
|
||||
|
||||
Full Data Flow (ABC‑F1 and ABC‑F2)
|
||||
==================================
|
||||
|
||||
The complete data flow includes:
|
||||
|
||||
* AppStack → Logical Units
|
||||
* Logical Units → Resource Groups
|
||||
* Resource Groups → Logical Units
|
||||
* Logical Units → AppStack
|
||||
|
||||
This is the full vertical chain required by the ABC Pattern.
|
||||
|
||||
Downward Flow (Capturing Down — ABC‑F1)
|
||||
---------------------------------------
|
||||
|
||||
#. AppStack → DataUnit
|
||||
* ``environment``
|
||||
* ``region``
|
||||
* ``storage_class``
|
||||
* ``db_engine``
|
||||
* ``db_instance_size``
|
||||
#. DataUnit → StorageGroup
|
||||
* ``environment``
|
||||
* ``region``
|
||||
* ``storage_class``
|
||||
#. DataUnit → DatabaseGroup
|
||||
* ``environment``
|
||||
* ``db_engine``
|
||||
* ``db_instance_size``
|
||||
#. AppStack → LogicUnit
|
||||
|
||||
* ``environment``
|
||||
* ``region``
|
||||
* ``compute_size``
|
||||
* ``message_retention``
|
||||
* ``database_endpoint`` (bubbled up from DataUnit)
|
||||
#. LogicUnit → ComputeGroup
|
||||
* ``environment``
|
||||
* ``compute_size``
|
||||
* ``database_endpoint``
|
||||
#. LogicUnit → MessagingGroup
|
||||
* ``environment``
|
||||
* ``message_retention``
|
||||
#. AppStack → PresentationUnit
|
||||
* ``environment``
|
||||
* ``region``
|
||||
* ``frontend_assets_bucket``
|
||||
* ``api_endpoint`` (bubbled up from LogicUnit)
|
||||
#. PresentationUnit → WebAppGroup
|
||||
* ``environment``
|
||||
* ``frontend_assets_bucket``
|
||||
* ``api_endpoint``
|
||||
#. PresentationUnit → CDNGroup
|
||||
* ``environment``
|
||||
* ``webapp_origin_url`` (bubbled up from WebAppGroup)
|
||||
|
||||
Upward Flow (Bubbling Up — ABC‑F2)
|
||||
----------------------------------
|
||||
|
||||
#. StorageGroup → DataUnit
|
||||
* ``storage_bucket_name``
|
||||
#. DatabaseGroup → DataUnit
|
||||
* ``database_endpoint``
|
||||
#. DataUnit → AppStack
|
||||
* ``storage_bucket_name``
|
||||
* ``database_endpoint``
|
||||
#. ComputeGroup → LogicUnit
|
||||
* ``api_endpoint``
|
||||
#. MessagingGroup → LogicUnit
|
||||
* ``message_queue_url``
|
||||
#. LogicUnit → AppStack
|
||||
* ``api_endpoint``
|
||||
* ``message_queue_url``
|
||||
#. WebAppGroup → PresentationUnit
|
||||
* ``webapp_origin_url``
|
||||
#. CDNGroup → PresentationUnit
|
||||
* ``frontend_url``
|
||||
#. PresentationUnit → AppStack
|
||||
* ``frontend_url``
|
||||
|
||||
Rationale
|
||||
=========
|
||||
|
||||
This example demonstrates:
|
||||
|
||||
* Strict encapsulation
|
||||
* Explicit dependencies
|
||||
* No lateral references
|
||||
* Deterministic wiring
|
||||
* Testability at every level
|
||||
* Predictable evolution
|
||||
* Agent‑friendly structure
|
||||
|
||||
It is the canonical reference for all profiles (CDK, Terraform, etc.).
|
||||
98
src/index.rst
Normal file
98
src/index.rst
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
###################
|
||||
Abstract Base Cloud
|
||||
###################
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Content
|
||||
=======
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
concepts
|
||||
model
|
||||
rules/index
|
||||
schema
|
||||
example
|
||||
profiles/index
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
AGENTS
|
||||
207
src/model.rst
Normal file
207
src/model.rst
Normal file
|
|
@ -0,0 +1,207 @@
|
|||
##############
|
||||
Abstract Model
|
||||
##############
|
||||
|
||||
Hierarchy Model
|
||||
===============
|
||||
|
||||
The ABC Pattern defines a strict three‑layer hierarchy of constructs (ABC‑C0):
|
||||
|
||||
* Application Stack (ABC‑C1) — the root deployment boundary.
|
||||
* Logical Units (ABC‑C2) — first‑level domains within the application.
|
||||
* Resource Groups (ABC‑C3) — fine‑grained functional clusters inside each
|
||||
Logical Unit.
|
||||
|
||||
This hierarchy is **strictly vertical**.
|
||||
|
||||
Every construct belongs to exactly one parent, and no construct may exist
|
||||
outside this tree.
|
||||
|
||||
The hierarchy expresses **encapsulation**:
|
||||
|
||||
* ABC‑C1 encapsulates the entire application.
|
||||
* ABC‑C2 encapsulates domain‑level concerns.
|
||||
* ABC‑C3 encapsulates resource‑level concerns.
|
||||
|
||||
Each layer exposes its behavior exclusively through its Instantiation Interface
|
||||
(ABC‑C6) and its Input/Output Contracts (ABC‑C4, ABC‑C5).
|
||||
|
||||
Relationship Semantics
|
||||
======================
|
||||
|
||||
The ABC Pattern enforces a parent–child‑only relationship model.
|
||||
|
||||
Allowed relationships
|
||||
---------------------
|
||||
|
||||
A parent construct MAY instantiate children using the child’s Instantiation
|
||||
Interface (ABC‑C6).
|
||||
|
||||
A child MAY expose outputs upward via its Output Contract (ABC‑C5).
|
||||
|
||||
A parent MAY route outputs from one child to another via Capturing Down
|
||||
(ABC‑C7).
|
||||
|
||||
Forbidden relationships
|
||||
-----------------------
|
||||
|
||||
* **No lateral references:**
|
||||
|
||||
- Resource Groups (ABC‑C3) may not reference each other directly.
|
||||
- Logical Units (ABC‑C2) may not reference each other directly.
|
||||
* **No implicit dependencies:**
|
||||
|
||||
- A construct may not read global state, shared variables, or parent
|
||||
internals.
|
||||
* **No hidden communication channels:**
|
||||
|
||||
- All data must flow through Input/Output Contracts.
|
||||
|
||||
These constraints ensure loose coupling, testability, and predictable
|
||||
composition.
|
||||
|
||||
Interface Semantics
|
||||
===================
|
||||
|
||||
Every construct (ABC‑C0) defines two explicit interfaces:
|
||||
|
||||
Input Contract (ABC‑C4)
|
||||
-----------------------
|
||||
|
||||
The complete set of parameters required for instantiation.
|
||||
A construct MUST NOT depend on any value not present in its Input Contract.
|
||||
|
||||
Output Contract (ABC‑C5)
|
||||
------------------------
|
||||
|
||||
The complete set of values the construct exposes upward.
|
||||
A construct MUST NOT leak internal state except through this contract.
|
||||
|
||||
Interface Binding
|
||||
-----------------
|
||||
|
||||
When a parent instantiates a child:
|
||||
|
||||
#. The parent supplies the child’s Input Contract.
|
||||
#. The child returns its Output Contract.
|
||||
#. The parent may:
|
||||
|
||||
* consume the outputs,
|
||||
* aggregate them,
|
||||
* or pass them down to other children.
|
||||
|
||||
This creates a **closed, explicit dependency graph** with no hidden edges.
|
||||
|
||||
Instantiation Semantics
|
||||
=======================
|
||||
|
||||
The Instantiation Interface (ABC‑C6) is the single mechanism through which a
|
||||
construct is created.
|
||||
|
||||
It has three properties:
|
||||
|
||||
* **Stability** - The interface remains stable even if internal implementation
|
||||
changes.
|
||||
* **Minimality** - Only the Input Contract is accepted; no additional
|
||||
parameters.
|
||||
* **Purity** - Instantiation has no side effects beyond constructing the child.
|
||||
|
||||
Instantiation is always **top‑down**:
|
||||
|
||||
* ABC‑C1 instantiates ABC‑C2 constructs.
|
||||
* ABC‑C2 instantiates ABC‑C3 constructs.
|
||||
* No construct may instantiate its parent or siblings.
|
||||
|
||||
This ensures deterministic composition and predictable dependency flow.
|
||||
|
||||
Data Flow Semantics
|
||||
===================
|
||||
|
||||
Data flows vertically through two complementary mechanisms:
|
||||
|
||||
ABC‑F1 — Capturing Down (maps to ABC‑C7)
|
||||
----------------------------------------
|
||||
|
||||
A parent passes scoped inputs to its children.
|
||||
|
||||
This mechanism ensures:
|
||||
|
||||
* Children receive only what they need.
|
||||
* No child can access parent state implicitly.
|
||||
* Parents mediate all cross‑domain dependencies.
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
The Application Stack (ABC‑C1) passes a VPC ID to a Logical Unit (ABC‑C2),
|
||||
which passes a subnet ID to a Resource Group (ABC‑C3).
|
||||
|
||||
ABC‑F2 — Bubbling Up (maps to ABC‑C8)
|
||||
-------------------------------------
|
||||
|
||||
A child exposes outputs upward to its parent.
|
||||
|
||||
This mechanism ensures:
|
||||
|
||||
* All produced values are explicit.
|
||||
* Parents can aggregate or route outputs.
|
||||
* No child communicates directly with siblings.
|
||||
|
||||
.. admonition:: Example
|
||||
|
||||
A Database Resource Group returns a database endpoint to its Logical Unit,
|
||||
which returns it to the Application Stack.
|
||||
|
||||
Routing Semantics
|
||||
-----------------
|
||||
|
||||
Parents MAY:
|
||||
|
||||
* **Consume** outputs (e.g., store them).
|
||||
* **Transform** outputs (e.g., wrap them in a composite object).
|
||||
* **Re‑expose** outputs upward.
|
||||
* **Pass** outputs downward to other children.
|
||||
|
||||
Children MAY not route data themselves.
|
||||
|
||||
Conceptual Diagram
|
||||
==================
|
||||
|
||||
.. code-block::
|
||||
|
||||
Application Stack (ABC‑C1)
|
||||
│
|
||||
├── Logical Unit: Data (ABC‑C2)
|
||||
│ ├── Resource Group: Storage (ABC‑C3)
|
||||
│ └── Resource Group: Database (ABC‑C3)
|
||||
│
|
||||
├── Logical Unit: Logic (ABC‑C2)
|
||||
│ ├── Resource Group: Compute (ABC‑C3)
|
||||
│ └── Resource Group: Messaging (ABC‑C3)
|
||||
│
|
||||
└── Logical Unit: Presentation (ABC‑C2)
|
||||
├── Resource Group: CDN (ABC‑C3)
|
||||
└── Resource Group: WebApp (ABC‑C3)
|
||||
|
||||
**Downward arrows** represent Capturing Down (ABC‑F1).
|
||||
|
||||
**Upward arrows** represent Bubbling Up (ABC‑F2).
|
||||
|
||||
No horizontal arrows exist.
|
||||
|
||||
Rationale & Design Intent
|
||||
=========================
|
||||
|
||||
The ABC Pattern enforces a strict, explicit, and testable structure for cloud
|
||||
infrastructure code.
|
||||
|
||||
* **Encapsulation** ensures each construct hides its internal details.
|
||||
* **Explicit interfaces** eliminate hidden dependencies.
|
||||
* **Loose coupling** prevents cross‑domain entanglement.
|
||||
* **Reusability** emerges from stable Instantiation Interfaces.
|
||||
* **Testability** is guaranteed because each construct can be instantiated with
|
||||
mock inputs.
|
||||
* **Scalability** follows naturally from the ability to evolve constructs
|
||||
independently.
|
||||
|
||||
This model is intentionally tool‑agnostic so it can be mapped cleanly to CDK,
|
||||
Terraform, Pulumi, or any imperative, as well as declarative IaC framework.
|
||||
442
src/profiles/cdk-ts.rst
Normal file
442
src/profiles/cdk-ts.rst
Normal file
|
|
@ -0,0 +1,442 @@
|
|||
######################
|
||||
CDK TypeScript Profile
|
||||
######################
|
||||
|
||||
Concept → CDK Mapping
|
||||
=====================
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - ABC Concept
|
||||
- Meaning
|
||||
- CDK Mapping
|
||||
* - ABC‑C0
|
||||
- Construct
|
||||
- ``Construct`` subclass
|
||||
* - ABC‑C1
|
||||
- Application Stack
|
||||
- ``Stack`` subclass
|
||||
* - ABC‑C2
|
||||
- Logical Unit (LU)
|
||||
- ``Construct`` subclass with LU semantics
|
||||
* - ABC‑C3
|
||||
- Resource Group (RG)
|
||||
- ``Construct`` subclass with RG semantics
|
||||
* - ABC‑C4
|
||||
- Input Contract
|
||||
- TypeScript interface (``InputContract``)
|
||||
* - ABC‑C5
|
||||
- Output Contract
|
||||
- TypeScript interface (``OutputContract``)
|
||||
* - ABC‑C6
|
||||
- Instantiation Interface
|
||||
- Constructor (``scope``, ``id``, ``inputs``)
|
||||
* - ABC‑C7
|
||||
- Capturing Down
|
||||
- Passing inputs to children
|
||||
* - ABC‑C8
|
||||
- Bubbling Up
|
||||
- Exposing outputs upward
|
||||
|
||||
*ABC* itself remains naming‑agnostic; this profile defines CDK‑idiomatic
|
||||
conventions.
|
||||
|
||||
Rules
|
||||
=====
|
||||
|
||||
These are profile‑specific rules for CDK-Typescript users.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R1 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
The directory structure SHOULD reflect the ABC hierarchy:
|
||||
|
||||
Application Stack → Logical Units → Resource Groups.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R2 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
Each Logical Unit SHOULD reside in its own top‑level directory:
|
||||
|
||||
.. code-block::
|
||||
|
||||
src/
|
||||
app-stack.ts
|
||||
data/
|
||||
logic/
|
||||
presentation/
|
||||
|
||||
ABC-PROFILE-CDKTS‑R3 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
Each Resource Group SHOULD reside inside its parent Logical Unit:
|
||||
|
||||
|
||||
.. code-block::
|
||||
|
||||
src/data/storage/
|
||||
src/data/database/
|
||||
|
||||
ABC-PROFILE-CDKTS‑R4 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
Each construct directory SHOULD contain an index.ts exporting the construct.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R5 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
File and directory names SHOULD follow CDK naming conventions.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R6 (MAY)
|
||||
--------------------------
|
||||
|
||||
Modules MAY split into multiple files if needed, as long as they remain in the
|
||||
same directory.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R7 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
Each construct module SHOULD define its own ``InputContract`` and
|
||||
``OutputContract``.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R8 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
Within a module, contracts SHOULD be named simply ``InputContract`` and
|
||||
``OutputContract``.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R9 (SHOULD)
|
||||
-----------------------------
|
||||
|
||||
When importing contracts from another module, they SHOULD be aliased:
|
||||
|
||||
ABC-PROFILE-CDKTS‑R10 (MUST)
|
||||
----------------------------
|
||||
|
||||
Constructs MUST be instantiated using a single InputContract object.
|
||||
|
||||
Also see ABC‑R30/32.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R11 (MUST)
|
||||
----------------------------
|
||||
|
||||
All cross‑construct wiring MUST occur in the parent construct.
|
||||
|
||||
Also see ABC‑R44.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R12 (SHOULD)
|
||||
------------------------------
|
||||
|
||||
Imported contracts SHOULD be aliased to descriptive names.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R13 (SHOULD)
|
||||
------------------------------
|
||||
|
||||
Contracts SHOULD be co‑located with their construct modules.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R14 (SHOULD)
|
||||
------------------------------
|
||||
|
||||
Generated code SHOULD mirror the ABC hierarchy in structure and composition.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R15 (SHOULD)
|
||||
------------------------------
|
||||
|
||||
Construct internals SHOULD NOT be accessed except through outputs.
|
||||
|
||||
ABC-PROFILE-CDKTS‑R16 (SHOULD)
|
||||
------------------------------
|
||||
|
||||
Constructs SHOULD be generated in ABC order: Resource Groups → Logical Units →
|
||||
Application Stack.
|
||||
|
||||
Base ABC Classes for Typescript-CDK
|
||||
===================================
|
||||
|
||||
Core Types
|
||||
----------
|
||||
|
||||
.. code-block:: javascript
|
||||
:caption: src/abc/core-types.ts
|
||||
|
||||
export interface InputContract {}
|
||||
export interface OutputContract {}
|
||||
|
||||
export interface HasOutputs<TOutputs extends OutputContract> {
|
||||
readonly outputs: TOutputs;
|
||||
}
|
||||
|
||||
Application Stack Base
|
||||
----------------------
|
||||
|
||||
.. code-block:: javascript
|
||||
:caption: src/abc/application-stack.ts
|
||||
|
||||
import { Stack, StackProps } from 'aws-cdk-lib';
|
||||
import { Construct } from 'constructs';
|
||||
import { OutputContract } from './core-types';
|
||||
|
||||
export abstract class ABCApplicationStack<
|
||||
TOutputs extends OutputContract = OutputContract
|
||||
> extends Stack {
|
||||
public abstract readonly outputs: TOutputs;
|
||||
|
||||
protected constructor(scope: Construct, id: string, props?: StackProps) {
|
||||
super(scope, id, props);
|
||||
}
|
||||
}
|
||||
|
||||
Logical Unit Base
|
||||
-----------------
|
||||
|
||||
.. code-block:: javascript
|
||||
:caption: src/abc/logical-unit.ts
|
||||
|
||||
import { Construct } from 'constructs';
|
||||
import { InputContract, OutputContract, HasOutputs } from './core-types';
|
||||
|
||||
export abstract class ABCLogicalUnit<
|
||||
TInputs extends InputContract,
|
||||
TOutputs extends OutputContract
|
||||
> extends Construct implements HasOutputs<TOutputs> {
|
||||
public abstract readonly outputs: TOutputs;
|
||||
protected readonly inputs: TInputs;
|
||||
|
||||
protected constructor(scope: Construct, id: string, inputs: TInputs) {
|
||||
super(scope, id);
|
||||
this.inputs = Object.freeze({ ...inputs }) as TInputs;
|
||||
}
|
||||
}
|
||||
|
||||
Resource Group Base
|
||||
-------------------
|
||||
|
||||
.. code-block:: javascript
|
||||
:caption: src/abc/resource-group.ts
|
||||
|
||||
import { Construct } from 'constructs';
|
||||
import { InputContract, OutputContract, HasOutputs } from './core-types';
|
||||
|
||||
export abstract class ABCResourceGroup<
|
||||
TInputs extends InputContract,
|
||||
TOutputs extends OutputContract
|
||||
> extends Construct implements HasOutputs<TOutputs> {
|
||||
public abstract readonly outputs: TOutputs;
|
||||
protected readonly inputs: TInputs;
|
||||
|
||||
protected constructor(scope: Construct, id: string, inputs: TInputs) {
|
||||
super(scope, id);
|
||||
this.inputs = Object.freeze({ ...inputs }) as TInputs;
|
||||
}
|
||||
}
|
||||
|
||||
Logical Units & Resource Groups (Canonical Example)
|
||||
===================================================
|
||||
|
||||
Below is the full 3‑tier example implemented in CDK.
|
||||
|
||||
Data Logical Unit
|
||||
-----------------
|
||||
|
||||
.. code-block::
|
||||
|
||||
src/data/index.ts
|
||||
src/data/storage/index.ts
|
||||
src/data/database/index.ts
|
||||
|
||||
.. code-block:: javascript
|
||||
:caption: src/data/index.ts
|
||||
|
||||
import { Construct } from 'constructs';
|
||||
import { ABCLogicalUnit } from '../abc/logical-unit';
|
||||
import { StorageGroup } from './storage';
|
||||
import { DatabaseGroup } from './database';
|
||||
|
||||
export interface InputContract {
|
||||
environment: string;
|
||||
region: string;
|
||||
storageClass: string;
|
||||
dbEngine: string;
|
||||
dbInstanceSize: string;
|
||||
}
|
||||
|
||||
export interface OutputContract {
|
||||
storageBucketName: string;
|
||||
databaseEndpoint: string;
|
||||
}
|
||||
|
||||
export class DataUnit extends ABCLogicalUnit<InputContract, OutputContract> {
|
||||
public readonly outputs: OutputContract;
|
||||
|
||||
constructor(scope: Construct, id: string, inputs: InputContract) {
|
||||
super(scope, id, inputs);
|
||||
|
||||
const storage = new StorageGroup(this, 'Storage', {
|
||||
environment: inputs.environment,
|
||||
region: inputs.region,
|
||||
storageClass: inputs.storageClass,
|
||||
});
|
||||
|
||||
const database = new DatabaseGroup(this, 'Database', {
|
||||
environment: inputs.environment,
|
||||
dbEngine: inputs.dbEngine,
|
||||
dbInstanceSize: inputs.dbInstanceSize,
|
||||
});
|
||||
|
||||
this.outputs = {
|
||||
storageBucketName: storage.outputs.storageBucketName,
|
||||
databaseEndpoint: database.outputs.databaseEndpoint,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
Storage Resource Group
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
:caption: src/data/storage/index.ts
|
||||
|
||||
import { Construct } from 'constructs';
|
||||
import { ABCResourceGroup } from '../../abc/resource-group';
|
||||
|
||||
export interface InputContract {
|
||||
environment: string;
|
||||
region: string;
|
||||
storageClass: string;
|
||||
}
|
||||
|
||||
export interface OutputContract {
|
||||
storageBucketName: string;
|
||||
}
|
||||
|
||||
export class StorageGroup extends ABCResourceGroup<InputContract, OutputContract> {
|
||||
public readonly outputs: OutputContract;
|
||||
|
||||
constructor(scope: Construct, id: string, inputs: InputContract) {
|
||||
super(scope, id, inputs);
|
||||
|
||||
this.outputs = {
|
||||
storageBucketName: 'bucket-name-placeholder',
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
Database Resource Group
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block::
|
||||
:caption: src/data/database/index.ts
|
||||
|
||||
import { Construct } from 'constructs';
|
||||
import { ABCResourceGroup } from '../../abc/resource-group';
|
||||
|
||||
export interface InputContract {
|
||||
environment: string;
|
||||
dbEngine: string;
|
||||
dbInstanceSize: string;
|
||||
}
|
||||
|
||||
export interface OutputContract {
|
||||
databaseEndpoint: string;
|
||||
}
|
||||
|
||||
export class DatabaseGroup extends ABCResourceGroup<InputContract, OutputContract> {
|
||||
public readonly outputs: OutputContract;
|
||||
|
||||
constructor(scope: Construct, id: string, inputs: InputContract) {
|
||||
super(scope, id, inputs);
|
||||
|
||||
this.outputs = {
|
||||
databaseEndpoint: 'db-endpoint-placeholder',
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
Logic Logical Unit
|
||||
------------------
|
||||
|
||||
.. code-block::
|
||||
|
||||
src/logic/index.ts
|
||||
src/logic/compute/index.ts
|
||||
src/logic/messaging/index.ts
|
||||
|
||||
Compute Resource Group and Messaging Resource Group follow the same pattern.
|
||||
|
||||
Presentation Logical Unit
|
||||
-------------------------
|
||||
|
||||
.. code-block::
|
||||
|
||||
src/presentation/index.ts
|
||||
src/presentation/webapp/index.ts
|
||||
src/presentation/cdn/index.ts
|
||||
|
||||
WebApp Resource Group and CDN Resource Group follow the same pattern.
|
||||
|
||||
Application Stack
|
||||
=================
|
||||
|
||||
.. code-block:: javascript
|
||||
:caption: src/app-stack.ts
|
||||
|
||||
import { Construct } from 'constructs';
|
||||
import { ABCApplicationStack } from './abc/application-stack';
|
||||
import { DataUnit } from './data';
|
||||
import type { InputContract as DataUnitInput } from './data';
|
||||
import { LogicUnit } from './logic';
|
||||
import type { InputContract as LogicUnitInput } from './logic';
|
||||
import { PresentationUnit } from './presentation';
|
||||
import type { InputContract as PresentationUnitInput } from './presentation';
|
||||
|
||||
export interface InputContract {
|
||||
environment: string;
|
||||
region: string;
|
||||
globalTags?: Record<string, string>;
|
||||
}
|
||||
|
||||
export interface OutputContract {
|
||||
frontendUrl: string;
|
||||
apiEndpoint: string;
|
||||
}
|
||||
|
||||
export class AppStack extends ABCApplicationStack<OutputContract> {
|
||||
public readonly outputs: OutputContract;
|
||||
|
||||
constructor(scope: Construct, id: string, inputs: InputContract) {
|
||||
super(scope, id);
|
||||
|
||||
const dataInputs: DataUnitInput = {
|
||||
environment: inputs.environment,
|
||||
region: inputs.region,
|
||||
storageClass: 'STANDARD',
|
||||
dbEngine: 'postgres',
|
||||
dbInstanceSize: 'db.t3.micro',
|
||||
};
|
||||
const dataUnit = new DataUnit(this, 'DataUnit', dataInputs);
|
||||
|
||||
const logicInputs: LogicUnitInput = {
|
||||
environment: inputs.environment,
|
||||
region: inputs.region,
|
||||
computeSize: 'small',
|
||||
messageRetention: 1209600,
|
||||
databaseEndpoint: dataUnit.outputs.databaseEndpoint,
|
||||
};
|
||||
const logicUnit = new LogicUnit(this, 'LogicUnit', logicInputs);
|
||||
|
||||
const presentationInputs: PresentationUnitInput = {
|
||||
environment: inputs.environment,
|
||||
region: inputs.region,
|
||||
frontendAssetsBucket: dataUnit.outputs.storageBucketName,
|
||||
apiEndpoint: logicUnit.outputs.apiEndpoint,
|
||||
};
|
||||
const presentationUnit = new PresentationUnit(this, 'PresentationUnit', presentationInputs);
|
||||
|
||||
this.outputs = {
|
||||
frontendUrl: presentationUnit.outputs.frontendUrl,
|
||||
apiEndpoint: logicUnit.outputs.apiEndpoint,
|
||||
};
|
||||
}
|
||||
}
|
||||
|
||||
26
src/profiles/index.rst
Normal file
26
src/profiles/index.rst
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
########
|
||||
Profiles
|
||||
########
|
||||
|
||||
Profiles define how the ABC Pattern maps onto specific IaC tools. Each profile
|
||||
introduces additional rules, conventions, and examples tailored to the target
|
||||
system.
|
||||
|
||||
Profiles use identifiers of the form:
|
||||
|
||||
.. code-block::
|
||||
|
||||
ABC-PROFILE-<PROFILE>-R#
|
||||
|
||||
Current profiles include:
|
||||
|
||||
* imperative, object‑oriented implementations
|
||||
* declarative module‑based implementation
|
||||
|
||||
Profiles demonstrate that ABC is not tied to any particular paradigm.
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
*
|
||||
249
src/profiles/tf.rst
Normal file
249
src/profiles/tf.rst
Normal file
|
|
@ -0,0 +1,249 @@
|
|||
#################
|
||||
Terraform Profile
|
||||
#################
|
||||
|
||||
Concept → Terraform Mapping
|
||||
===========================
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
|
||||
* - ABC Concept
|
||||
- Meaning
|
||||
- Terraform Mapping
|
||||
* - ABC‑C0
|
||||
- Construct
|
||||
- Terraform module
|
||||
* - ABC‑C1
|
||||
- Application Stack
|
||||
- Root Terraform module
|
||||
* - ABC‑C2
|
||||
- Logical Unit
|
||||
- Child module representing a domain
|
||||
* - ABC‑C3
|
||||
- Resource Group
|
||||
- Submodule representing a cohesive resource cluster
|
||||
* - ABC‑C4
|
||||
- Input Contract
|
||||
- variables.tf in a module
|
||||
* - ABC‑C5
|
||||
- Output Contract
|
||||
- outputs.tf in a module
|
||||
* - ABC‑C6
|
||||
- Instantiation Interface
|
||||
- ``module "" { ... }`` block
|
||||
* - ABC‑C7
|
||||
- Capturing Down
|
||||
- Passing variables from parent to child module
|
||||
* - ABC‑C8
|
||||
- Bubbling Up
|
||||
- Exposing outputs from child modules to parent
|
||||
|
||||
Proile Rules
|
||||
============
|
||||
|
||||
Terraform profile rules follow the canonical identifier format:
|
||||
|
||||
.. code-block::
|
||||
|
||||
ABC-PROFILE-TF-R#
|
||||
|
||||
These rules are profile‑specific, not core ABC rules.
|
||||
|
||||
ABC-PROFILE-TF-R1 (SHOULD)
|
||||
--------------------------
|
||||
|
||||
Each ABC construct SHOULD be implemented as a Terraform module.
|
||||
|
||||
ABC-PROFILE-TF-R2 (SHOULD)
|
||||
--------------------------
|
||||
|
||||
The directory structure SHOULD reflect the ABC hierarchy:
|
||||
|
||||
.. code-block::
|
||||
|
||||
root/
|
||||
main.tf
|
||||
data/
|
||||
main.tf
|
||||
storage/
|
||||
main.tf
|
||||
database/
|
||||
main.tf
|
||||
logic/
|
||||
main.tf
|
||||
presentation/
|
||||
main.tf
|
||||
|
||||
ABC-PROFILE-TF-R3 (SHOULD)
|
||||
--------------------------
|
||||
|
||||
Each module SHOULD contain:
|
||||
|
||||
* main.tf
|
||||
* variables.tf (InputContract)
|
||||
* outputs.tf (OutputContract)
|
||||
|
||||
ABC-PROFILE-TF-R4 (MUST)
|
||||
------------------------
|
||||
|
||||
Module inputs MUST be declared exclusively in variables.tf.
|
||||
|
||||
ABC-PROFILE-TF-R5 (MUST)
|
||||
------------------------
|
||||
|
||||
Module outputs MUST be declared exclusively in outputs.tf.
|
||||
|
||||
ABC-PROFILE-TF-R6 (MUST)
|
||||
------------------------
|
||||
|
||||
Modules MUST NOT reference parent or sibling modules directly; all data MUST
|
||||
flow through variables and outputs.
|
||||
|
||||
(This enforces ABC‑R22, ABC‑R40, ABC‑R42.)
|
||||
|
||||
ABC-PROFILE-TF-R7 (MUST)
|
||||
------------------------
|
||||
|
||||
Modules MUST be instantiated using a module "<name>" { ... } block with explicit
|
||||
variable assignments.
|
||||
|
||||
ABC-PROFILE-TF-R8 (MUST)
|
||||
------------------------
|
||||
|
||||
Modules MUST NOT read Terraform state from other modules except via outputs.
|
||||
|
||||
ABC-PROFILE-TF-R9 (MUST)
|
||||
------------------------
|
||||
|
||||
Capturing Down MUST be implemented by passing parent variables or outputs into
|
||||
child module inputs.
|
||||
|
||||
ABC-PROFILE-TF-R10 (MUST)
|
||||
-------------------------
|
||||
|
||||
Bubbling Up MUST be implemented by exposing child module outputs and re‑exposing
|
||||
them in the parent module if needed.
|
||||
|
||||
ABC-PROFILE-TF-R11 (MUST)
|
||||
-------------------------
|
||||
|
||||
Resource definitions MUST reside only in Resource Group modules (ABC‑C3).
|
||||
|
||||
ABC-PROFILE-TF-R12 (MUST)
|
||||
-------------------------
|
||||
|
||||
Logical Units MUST NOT contain Terraform resources directly.
|
||||
|
||||
ABC-PROFILE-TF-R13 (SHOULD)
|
||||
---------------------------
|
||||
|
||||
Logical Units SHOULD only orchestrate child modules and expose aggregated
|
||||
outputs.
|
||||
|
||||
Canonical Example
|
||||
=================
|
||||
|
||||
A minimal 3‑tier ABC architecture in Terraform.
|
||||
|
||||
Application Stack
|
||||
-----------------
|
||||
|
||||
.. code-block:: hcl
|
||||
:caption: main.tf
|
||||
|
||||
module "data" {
|
||||
source = "./data"
|
||||
environment = var.environment
|
||||
region = var.region
|
||||
}
|
||||
|
||||
module "logic" {
|
||||
source = "./logic"
|
||||
environment = var.environment
|
||||
region = var.region
|
||||
database_endpoint = module.data.database_endpoint
|
||||
}
|
||||
|
||||
module "presentation" {
|
||||
source = "./presentation"
|
||||
environment = var.environment
|
||||
region = var.region
|
||||
frontend_assets_bucket = module.data.storage_bucket_name
|
||||
api_endpoint = module.logic.api_endpoint
|
||||
}
|
||||
|
||||
output "frontend_url" {
|
||||
value = module.presentation.frontend_url
|
||||
}
|
||||
|
||||
output "api_endpoint" {
|
||||
value = module.logic.api_endpoint
|
||||
}
|
||||
|
||||
.. code-block:: hcl
|
||||
:caption: variables.tf
|
||||
|
||||
variable "environment" { type = string }
|
||||
variable "region" { type = string }
|
||||
|
||||
Data Logical Unit
|
||||
-----------------
|
||||
|
||||
.. code-block::
|
||||
:caption: data/main.tf
|
||||
|
||||
module "storage" {
|
||||
source = "./storage"
|
||||
environment = var.environment
|
||||
region = var.region
|
||||
storage_class = var.storage_class
|
||||
}
|
||||
|
||||
module "database" {
|
||||
source = "./database"
|
||||
environment = var.environment
|
||||
db_engine = var.db_engine
|
||||
db_instance_size = var.db_instance_size
|
||||
}
|
||||
|
||||
output "storage_bucket_name" {
|
||||
value = module.storage.bucket_name
|
||||
}
|
||||
|
||||
output "database_endpoint" {
|
||||
value = module.database.endpoint
|
||||
}
|
||||
|
||||
.. code-block::
|
||||
:caption: data/variables.tf
|
||||
|
||||
variable "environment" { type = string }
|
||||
variable "region" { type = string }
|
||||
variable "storage_class" { type = string }
|
||||
variable "db_engine" { type = string }
|
||||
variable "db_instance_size" { type = string }
|
||||
|
||||
Storage Resource Group
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. code-block:: hcl
|
||||
:caption: data/storage/main.tf
|
||||
|
||||
resource "aws_s3_bucket" "bucket" {
|
||||
bucket = "${var.environment}-storage"
|
||||
}
|
||||
|
||||
.. code-block:: hcl
|
||||
:caption: data/storage/variables.tf
|
||||
|
||||
variable "environment" { type = string }
|
||||
variable "region" { type = string }
|
||||
variable "storage_class" { type = string }
|
||||
|
||||
.. code-block:: hcl
|
||||
:caption: data/storage/outputs.tf
|
||||
|
||||
output "bucket_name" {
|
||||
value = aws_s3_bucket.bucket.bucket
|
||||
}
|
||||
26
src/rules/index.rst
Normal file
26
src/rules/index.rst
Normal file
|
|
@ -0,0 +1,26 @@
|
|||
#####
|
||||
Rules
|
||||
#####
|
||||
|
||||
The ABC Pattern is defined and enforced through two complementary rule families:
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 1
|
||||
|
||||
*
|
||||
|
||||
Together, these rule sets establish the semantic, structural, and mechanical
|
||||
guarantees that make ABC architectures predictable, verifiable, and safe for
|
||||
automated reasoning and transformation.
|
||||
|
||||
Although closely related, the two rule families serve distinct purposes:
|
||||
|
||||
**Normative Rules** define the semantic contract of the ABC Pattern. They
|
||||
specify what MUST, SHOULD, or MAY be true in any ABC‑compliant architecture,
|
||||
independent of implementation language, cloud provider, or IaC tool.
|
||||
|
||||
**Validation Rules** define the mechanical checks required to verify that an ABC
|
||||
architecture conforms to the Normative Rules and the ABC Schema. Where Normative
|
||||
Rules describe what must be true, Validation Rules describe how to detect
|
||||
violations.
|
||||
328
src/rules/normative.rst
Normal file
328
src/rules/normative.rst
Normal file
|
|
@ -0,0 +1,328 @@
|
|||
###############
|
||||
Normative Rules
|
||||
###############
|
||||
|
||||
The ABC Pattern is defined by a set of Normative Rules that establish the
|
||||
structural, behavioral, and data‑flow guarantees of the architecture. These
|
||||
rules are the foundation that makes ABC:
|
||||
|
||||
* predictable
|
||||
* composable
|
||||
* verifiable
|
||||
* agent‑friendly
|
||||
* implementation‑agnostic
|
||||
|
||||
Normative Rules describe what MUST or SHOULD be true in any ABC‑compliant
|
||||
architecture, regardless of the underlying cloud provider, IaC tool, or
|
||||
programming language. They are not suggestions or stylistic preferences; they
|
||||
are the semantic constraints that ensure ABC constructs behave consistently and
|
||||
safely.
|
||||
|
||||
Each rule is assigned a canonical identifier of the form:
|
||||
|
||||
.. code-block::
|
||||
|
||||
ABC-R#
|
||||
|
||||
This identifier is stable, unique, and referenced throughout:
|
||||
|
||||
* the ABC Schema
|
||||
* validation rules
|
||||
* implementation profiles (e.g., CDKTS, Terraform)
|
||||
* agent guidance
|
||||
* tooling and linters
|
||||
|
||||
Hierarchy Rules
|
||||
===============
|
||||
|
||||
These define the allowed structure of an ABC architecture, including the roles
|
||||
and relationships of ApplicationStacks, Logical Units, and Resource Groups.
|
||||
|
||||
ABC‑R1 (MUST)
|
||||
-------------
|
||||
|
||||
An Application Stack (ABC‑C1) MUST contain one or more Logical Units (ABC‑C2).
|
||||
|
||||
ABC‑R2 (MUST)
|
||||
-------------
|
||||
|
||||
A Logical Unit (ABC‑C2) MUST contain one or more Resource Groups (ABC‑C3).
|
||||
|
||||
ABC‑R3 (MUST)
|
||||
-------------
|
||||
|
||||
Every Construct (ABC‑C0) MUST have exactly one parent, except the Application
|
||||
Stack (ABC‑C1), which has none.
|
||||
|
||||
ABC‑R4 (MUST)
|
||||
-------------
|
||||
|
||||
Constructs MUST form a strict tree hierarchy with no cycles.
|
||||
|
||||
ABC‑R5 (SHOULD)
|
||||
---------------
|
||||
|
||||
Logical Units (ABC‑C2) SHOULD represent coherent functional domains.
|
||||
|
||||
ABC‑R6 (MAY)
|
||||
------------
|
||||
|
||||
Resource Groups (ABC‑C3) MAY be nested further if the implementation framework
|
||||
supports sub‑constructs, provided all other rules remain satisfied.
|
||||
|
||||
Relationship Rules
|
||||
==================
|
||||
|
||||
Specify how constructs relate to one another, including parent‑child
|
||||
constraints, allowed dependencies, and prohibited lateral references.
|
||||
|
||||
ABC‑R10 (MUST)
|
||||
--------------
|
||||
|
||||
A Resource Group (ABC‑C3) MUST NOT reference another Resource Group directly.
|
||||
|
||||
ABC‑R11 (MUST)
|
||||
--------------
|
||||
|
||||
A Logical Unit (ABC‑C2) MUST NOT reference another Logical Unit directly.
|
||||
|
||||
ABC‑R12 (MUST)
|
||||
--------------
|
||||
|
||||
A Construct (ABC‑C0) MUST NOT access parent state except through Capturing Down
|
||||
(ABC‑F1).
|
||||
|
||||
ABC‑R13 (MUST)
|
||||
--------------
|
||||
|
||||
A Construct (ABC‑C0) MUST NOT access sibling state under any circumstances.
|
||||
|
||||
ABC‑R14 (MUST)
|
||||
--------------
|
||||
|
||||
All cross‑domain communication MUST be mediated by the parent construct.
|
||||
|
||||
ABC‑R15 (SHOULD)
|
||||
----------------
|
||||
|
||||
Constructs SHOULD minimize the number of outputs they expose to reduce coupling.
|
||||
|
||||
ABC‑R16 (MAY)
|
||||
-------------
|
||||
|
||||
A parent MAY aggregate outputs from multiple children before re‑exposing them.
|
||||
|
||||
Interface Rules
|
||||
===============
|
||||
|
||||
Define the semantics of Input and Output Contracts, including immutability,
|
||||
explicitness, and the boundaries they enforce.
|
||||
|
||||
ABC‑R20 (MUST)
|
||||
--------------
|
||||
|
||||
Every Construct (ABC‑C0) MUST define an Input Contract (ABC‑C4).
|
||||
|
||||
ABC‑R21 (MUST)
|
||||
--------------
|
||||
|
||||
Every Construct (ABC‑C0) MUST define an Output Contract (ABC‑C5), even if empty.
|
||||
|
||||
ABC‑R22 (MUST)
|
||||
--------------
|
||||
|
||||
A Construct MUST NOT depend on any value not present in its Input Contract.
|
||||
|
||||
ABC‑R23 (MUST)
|
||||
--------------
|
||||
|
||||
A Construct MUST NOT expose any value not present in its Output Contract.
|
||||
|
||||
ABC‑R24 (MUST)
|
||||
--------------
|
||||
|
||||
Input Contracts MUST be immutable after instantiation.
|
||||
|
||||
ABC‑R25 (SHOULD)
|
||||
----------------
|
||||
|
||||
Output Contracts SHOULD be minimal and stable across versions.
|
||||
|
||||
ABC‑R26 (MAY)
|
||||
-------------
|
||||
|
||||
A Construct MAY expose composite outputs if they simplify parent‑level wiring.
|
||||
|
||||
Instantiation Rules
|
||||
===================
|
||||
|
||||
Specify how constructs are created, how inputs are provided, and how
|
||||
instantiation must avoid side effects or hidden dependencies.
|
||||
|
||||
ABC‑R30 (MUST)
|
||||
--------------
|
||||
|
||||
A Construct (ABC‑C0) MUST be instantiated exclusively through its Instantiation
|
||||
Interface (ABC‑C6).
|
||||
|
||||
ABC‑R31 (MUST)
|
||||
--------------
|
||||
|
||||
Instantiation MUST be top‑down: parents instantiate children; children MUST NOT
|
||||
instantiate parents or siblings.
|
||||
|
||||
ABC‑R32 (MUST)
|
||||
--------------
|
||||
|
||||
The Instantiation Interface MUST accept only the Input Contract (ABC‑C4) and no
|
||||
additional parameters.
|
||||
|
||||
ABC‑R33 (MUST)
|
||||
--------------
|
||||
|
||||
Instantiation MUST NOT produce side effects beyond constructing the child.
|
||||
|
||||
ABC‑R34 (SHOULD)
|
||||
----------------
|
||||
|
||||
Instantiation Interfaces SHOULD remain stable across minor revisions.
|
||||
|
||||
ABC‑R35 (MAY)
|
||||
-------------
|
||||
|
||||
Constructs MAY provide optional parameters in the Input Contract if defaults are
|
||||
well‑defined.
|
||||
|
||||
Data Flow Rules
|
||||
===============
|
||||
|
||||
Formalize the two fundamental ABC data‑flow mechanisms:
|
||||
|
||||
* Capturing Down (parent → child)
|
||||
* Bubbling Up (child → parent)
|
||||
|
||||
These rules ensure that all communication flows through the parent construct,
|
||||
eliminating ambiguity and hidden coupling.
|
||||
|
||||
ABC‑R40 (MUST)
|
||||
--------------
|
||||
|
||||
All downward data flow MUST occur through Capturing Down (ABC‑F1).
|
||||
|
||||
ABC‑R41 (MUST)
|
||||
--------------
|
||||
|
||||
All upward data flow MUST occur through Bubbling Up (ABC‑F2).
|
||||
|
||||
ABC‑R42 (MUST)
|
||||
--------------
|
||||
|
||||
A Construct MUST NOT read values from its parent except those explicitly passed
|
||||
via Capturing Down.
|
||||
|
||||
ABC‑R43 (MUST)
|
||||
--------------
|
||||
|
||||
A Construct MUST NOT write values to its parent except through Bubbling Up.
|
||||
|
||||
ABC‑R44 (MUST)
|
||||
--------------
|
||||
|
||||
Parents MUST mediate all routing of outputs between children.
|
||||
|
||||
ABC‑R45 (SHOULD)
|
||||
----------------
|
||||
Parents SHOULD avoid passing unnecessary outputs downward to reduce coupling.
|
||||
|
||||
ABC‑R46 (MAY)
|
||||
-------------
|
||||
|
||||
Parents MAY transform outputs before passing them down.
|
||||
|
||||
Encapsulation & Testability Rules
|
||||
=================================
|
||||
|
||||
Ensure that constructs remain isolated, testable, and free from cross‑cutting
|
||||
concerns. These rules prevent leakage of internal details and enforce strict
|
||||
boundaries.
|
||||
|
||||
ABC‑R50 (MUST)
|
||||
--------------
|
||||
|
||||
Constructs MUST encapsulate all internal implementation details.
|
||||
|
||||
ABC‑R51 (MUST)
|
||||
--------------
|
||||
|
||||
Constructs MUST be instantiable in isolation using mock Input Contracts.
|
||||
|
||||
ABC‑R52 (SHOULD)
|
||||
----------------
|
||||
|
||||
Constructs SHOULD avoid exposing internal resource identifiers unless required.
|
||||
|
||||
ABC‑R53 (SHOULD)
|
||||
----------------
|
||||
|
||||
Constructs SHOULD minimize internal state to simplify testing.
|
||||
|
||||
ABC‑R54 (MAY)
|
||||
-------------
|
||||
|
||||
Constructs MAY provide diagnostic outputs if they do not violate encapsulation.
|
||||
|
||||
Evolution & Change Management Rules
|
||||
===================================
|
||||
|
||||
Define how ABC architectures evolve safely over time, including versioning,
|
||||
contract stability, and backward‑compatible changes.
|
||||
|
||||
ABC‑R60 (MUST)
|
||||
--------------
|
||||
|
||||
If a child’s Output Contract changes, the parent MUST adapt explicitly.
|
||||
|
||||
ABC‑R61 (MUST)
|
||||
--------------
|
||||
|
||||
Breaking changes to Input Contracts MUST be versioned or documented.
|
||||
|
||||
ABC‑R62 (SHOULD)
|
||||
----------------
|
||||
|
||||
Constructs SHOULD maintain backward compatibility where feasible.
|
||||
|
||||
ABC‑R63 (SHOULD)
|
||||
----------------
|
||||
|
||||
Parents SHOULD validate child outputs before routing them.
|
||||
|
||||
ABC‑R64 (MAY)
|
||||
-------------
|
||||
|
||||
Constructs MAY deprecate fields gradually before removal.
|
||||
|
||||
Optional Flexibility Rules
|
||||
==========================
|
||||
|
||||
Provide non‑mandatory guidance that enhances clarity, maintainability, or
|
||||
ergonomics without affecting correctness. These rules are advisory and may be
|
||||
adopted at the discretion of the implementation or team.
|
||||
|
||||
ABC‑R70 (MAY)
|
||||
-------------
|
||||
|
||||
Logical Units MAY be composed dynamically if the framework supports it, provided
|
||||
all other rules remain satisfied.
|
||||
|
||||
ABC‑R71 (MAY)
|
||||
-------------
|
||||
|
||||
Resource Groups MAY be reused across Logical Units if instantiated
|
||||
independently.
|
||||
|
||||
ABC‑R72 (MAY)
|
||||
-------------
|
||||
|
||||
The Application Stack MAY expose a composite Output Contract aggregating all
|
||||
Logical Unit outputs.
|
||||
186
src/rules/validation.rst
Normal file
186
src/rules/validation.rst
Normal file
|
|
@ -0,0 +1,186 @@
|
|||
################
|
||||
Validation Rules
|
||||
################
|
||||
|
||||
The ABC Validation Rules define the mechanical checks required to verify that an
|
||||
ABC architecture conforms to the ABC Schema and the normative rules of the
|
||||
specification. These rules are intended for:
|
||||
|
||||
* automated validators
|
||||
* linters
|
||||
* compilers
|
||||
* agent‑driven code generation
|
||||
* CI/CD enforcement
|
||||
|
||||
Validation Rules are **not** conceptual rules; they are operational constraints
|
||||
that ensure an ABC description is structurally correct and unambiguous.
|
||||
|
||||
Validation Rules follow the canonical identifier format:
|
||||
|
||||
.. code-block::
|
||||
|
||||
ABC-VALID-R#
|
||||
|
||||
They are grouped into:
|
||||
|
||||
* Structural Validation
|
||||
* Contract Validation
|
||||
* Data‑Flow Validation
|
||||
* Hierarchy Validation
|
||||
* Profile‑Specific Validation (optional)
|
||||
|
||||
Structural Validation Rules
|
||||
===========================
|
||||
|
||||
These rules ensure the ABC hierarchy is well‑formed.
|
||||
|
||||
ABC-VALID-R1 (MUST)
|
||||
-------------------
|
||||
|
||||
Every construct MUST have exactly one parent, except the ApplicationStack which
|
||||
MUST have none.
|
||||
|
||||
ABC-VALID-R2 (MUST)
|
||||
-------------------
|
||||
|
||||
The hierarchy MUST follow the pattern:
|
||||
``ApplicationStack → LogicalUnit → ResourceGroup``.
|
||||
|
||||
ABC-VALID-R3 (MUST)
|
||||
-------------------
|
||||
|
||||
Construct trees MUST NOT contain cycles.
|
||||
|
||||
ABC-VALID-R4 (MUST)
|
||||
-------------------
|
||||
|
||||
Construct IDs MUST be unique within the architecture.
|
||||
|
||||
ABC-VALID-R5 (MUST)
|
||||
-------------------
|
||||
|
||||
Construct types MUST be one of:
|
||||
ApplicationStack, LogicalUnit, ResourceGroup.
|
||||
|
||||
ABC-VALID-R6 (MUST)
|
||||
-------------------
|
||||
|
||||
ResourceGroups MUST NOT have children.
|
||||
|
||||
ABC-VALID-R7 (MUST)
|
||||
-------------------
|
||||
|
||||
LogicalUnits MUST NOT have parents that are not ApplicationStacks.
|
||||
|
||||
ABC-VALID-R8 (MUST)
|
||||
-------------------
|
||||
|
||||
ResourceGroups MUST NOT have parents that are not LogicalUnits.
|
||||
|
||||
Contract Validation Rules
|
||||
=========================
|
||||
|
||||
These rules ensure Input/Output Contracts are well‑defined and consistent.
|
||||
|
||||
ABC-VALID-R10 (MUST)
|
||||
--------------------
|
||||
|
||||
Every construct MUST define both an InputContract and an OutputContract.
|
||||
|
||||
ABC-VALID-R11 (MUST)
|
||||
--------------------
|
||||
|
||||
InputContracts MUST be immutable after instantiation.
|
||||
|
||||
ABC-VALID-R12 (MUST)
|
||||
--------------------
|
||||
|
||||
Constructs MUST NOT reference values not present in their InputContract.
|
||||
|
||||
ABC-VALID-R13 (MUST)
|
||||
--------------------
|
||||
|
||||
Constructs MUST NOT expose outputs not declared in their OutputContract.
|
||||
|
||||
ABC-VALID-R14 (SHOULD)
|
||||
----------------------
|
||||
|
||||
OutputContracts SHOULD be minimal and stable across versions.
|
||||
|
||||
ABC-VALID-R15 (MUST)
|
||||
--------------------
|
||||
|
||||
InputContracts MUST NOT reference parent or sibling constructs directly.
|
||||
|
||||
ABC-VALID-R16 (MUST)
|
||||
--------------------
|
||||
|
||||
OutputContracts MUST NOT expose internal implementation details (e.g., resource
|
||||
objects).
|
||||
|
||||
Data‑Flow Validation Rules
|
||||
==========================
|
||||
|
||||
These rules enforce Capturing Down and Bubbling Up.
|
||||
|
||||
ABC-VALID-R20 (MUST)
|
||||
--------------------
|
||||
|
||||
All downward references MUST originate from:
|
||||
|
||||
* parent.InputContract
|
||||
* parent.OutputContract
|
||||
|
||||
ABC-VALID-R21 (MUST)
|
||||
--------------------
|
||||
|
||||
All upward references MUST originate from:
|
||||
|
||||
* child.OutputContract
|
||||
|
||||
ABC-VALID-R22 (MUST)
|
||||
--------------------
|
||||
|
||||
No lateral data flow is permitted between siblings.
|
||||
|
||||
ABC-VALID-R23 (MUST)
|
||||
--------------------
|
||||
|
||||
Constructs MUST NOT read values from grandparents or ancestors except through
|
||||
parent‑mediated Capturing Down.
|
||||
|
||||
ABC-VALID-R24 (MUST)
|
||||
--------------------
|
||||
|
||||
Constructs MUST NOT write values to ancestors except through Bubbling Up.
|
||||
|
||||
ABC-VALID-R25 (MUST)
|
||||
--------------------
|
||||
|
||||
Constructs MUST NOT read or write values from siblings or cousins.
|
||||
|
||||
Instantiation Validation Rules
|
||||
==============================
|
||||
|
||||
These rules ensure constructs are instantiated correctly.
|
||||
|
||||
ABC-VALID-R30 (MUST)
|
||||
--------------------
|
||||
|
||||
Constructs MUST be instantiated using the Instantiation Interface:
|
||||
(scope, id, inputs).
|
||||
|
||||
ABC-VALID-R31 (MUST)
|
||||
--------------------
|
||||
|
||||
Instantiation MUST NOT accept parameters outside the InputContract.
|
||||
|
||||
ABC-VALID-R32 (MUST)
|
||||
--------------------
|
||||
|
||||
Instantiation MUST NOT produce side effects beyond constructing children.
|
||||
|
||||
ABC-VALID-R33 (MUST)
|
||||
--------------------
|
||||
|
||||
Constructs MUST NOT mutate their InputContract after instantiation.
|
||||
229
src/schema.rst
Normal file
229
src/schema.rst
Normal file
|
|
@ -0,0 +1,229 @@
|
|||
######
|
||||
Schema
|
||||
######
|
||||
|
||||
The ABC Schema is the authoritative, machine‑readable definition of the ABC
|
||||
Pattern. It formalizes:
|
||||
|
||||
* Construct types
|
||||
* Hierarchy rules
|
||||
* Contract requirements
|
||||
* Data‑flow semantics
|
||||
* Instantiation constraints
|
||||
* Validation rules
|
||||
* Profile extension hooks
|
||||
|
||||
The schema is expressed as a single JSON Schema document, making it suitable
|
||||
for:
|
||||
|
||||
* Linting
|
||||
* Static analysis
|
||||
* Code generation
|
||||
* Agent reasoning
|
||||
* Architecture validation
|
||||
* Profile extension (CDKTS, Terraform, Pulumi, etc.)
|
||||
|
||||
This schema is intentionally strict. It defines the shape of an ABC
|
||||
architecture, not the cloud resources themselves. Profiles map this schema to
|
||||
concrete IaC implementations.
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://schema.tiararodney.com/abc/abc.schema.json",
|
||||
"title": "ABC Schema",
|
||||
"description": "The canonical machine-readable schema for the ABC Pattern.",
|
||||
"type": "object",
|
||||
|
||||
"properties": {
|
||||
"version": {
|
||||
"type": "string",
|
||||
"description": "Schema version identifier."
|
||||
},
|
||||
|
||||
"constructs": {
|
||||
"type": "array",
|
||||
"description": "List of constructs in the ABC architecture.",
|
||||
"items": { "$ref": "#/$defs/Construct" }
|
||||
}
|
||||
},
|
||||
|
||||
"required": ["version", "constructs"],
|
||||
|
||||
"$defs": {
|
||||
|
||||
"Construct": {
|
||||
"type": "object",
|
||||
"description": "A construct in the ABC hierarchy.",
|
||||
"properties": {
|
||||
"id": {
|
||||
"type": "string",
|
||||
"description": "Unique identifier for the construct."
|
||||
},
|
||||
"type": {
|
||||
"type": "string",
|
||||
"enum": ["ApplicationStack", "LogicalUnit", "ResourceGroup"],
|
||||
"description": "Construct type (ABC-C1, C2, or C3)."
|
||||
},
|
||||
"parent": {
|
||||
"type": ["string", "null"],
|
||||
"description": "Parent construct ID. Null only for ApplicationStack."
|
||||
},
|
||||
"inputs": {
|
||||
"$ref": "#/$defs/InputContract"
|
||||
},
|
||||
"outputs": {
|
||||
"$ref": "#/$defs/OutputContract"
|
||||
},
|
||||
"children": {
|
||||
"type": "array",
|
||||
"items": { "type": "string" },
|
||||
"description": "IDs of child constructs."
|
||||
}
|
||||
},
|
||||
"required": ["id", "type", "inputs", "outputs", "children"],
|
||||
"allOf": [
|
||||
{ "$ref": "#/$defs/HierarchyRules" },
|
||||
{ "$ref": "#/$defs/ContractRules" },
|
||||
{ "$ref": "#/$defs/DataFlowRules" }
|
||||
]
|
||||
},
|
||||
|
||||
"InputContract": {
|
||||
"type": "object",
|
||||
"description": "ABC-C4 Input Contract.",
|
||||
"additionalProperties": {
|
||||
"type": ["string", "number", "boolean", "object", "array", "null"]
|
||||
}
|
||||
},
|
||||
|
||||
"OutputContract": {
|
||||
"type": "object",
|
||||
"description": "ABC-C5 Output Contract.",
|
||||
"additionalProperties": {
|
||||
"type": ["string", "number", "boolean", "object", "array", "null"]
|
||||
}
|
||||
},
|
||||
|
||||
"HierarchyRules": {
|
||||
"type": "object",
|
||||
"description": "Hierarchy validation rules.",
|
||||
"properties": {},
|
||||
"allOf": [
|
||||
{
|
||||
"if": { "properties": { "type": { "const": "ApplicationStack" } } },
|
||||
"then": {
|
||||
"properties": {
|
||||
"parent": { "type": "null" }
|
||||
},
|
||||
"errorMessage": {
|
||||
"parent": "ABC-R3: ApplicationStack MUST have no parent."
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": { "properties": { "type": { "const": "LogicalUnit" } } },
|
||||
"then": {
|
||||
"properties": {
|
||||
"children": {
|
||||
"minItems": 1,
|
||||
"errorMessage": "ABC-R2: Logical Units MUST contain one or more Resource Groups."
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": { "properties": { "type": { "const": "ResourceGroup" } } },
|
||||
"then": {
|
||||
"properties": {
|
||||
"children": {
|
||||
"maxItems": 0,
|
||||
"errorMessage": "ABC-R10: Resource Groups MUST NOT contain child constructs."
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"ContractRules": {
|
||||
"type": "object",
|
||||
"description": "Contract validation rules.",
|
||||
"properties": {},
|
||||
"allOf": [
|
||||
{
|
||||
"properties": {
|
||||
"inputs": {
|
||||
"type": "object",
|
||||
"errorMessage": "ABC-R24: Input Contracts MUST be immutable objects."
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"properties": {
|
||||
"outputs": {
|
||||
"type": "object",
|
||||
"errorMessage": "ABC-R23: Output Contracts MUST be declared explicitly."
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
"DataFlowRules": {
|
||||
"type": "object",
|
||||
"description": "Data flow validation rules.",
|
||||
"properties": {},
|
||||
"allOf": [
|
||||
{
|
||||
"if": { "properties": { "type": { "const": "LogicalUnit" } } },
|
||||
"then": {
|
||||
"properties": {
|
||||
"inputs": {
|
||||
"type": "object"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
How Profiles Extend This Schema
|
||||
===============================
|
||||
|
||||
Profiles (e.g., Typescript CDK, Terraform) extend the monolithic schema using
|
||||
JSON Schema’s allOf mechanism.
|
||||
|
||||
.. code-block:: json
|
||||
:caption: https://schema.tiararodney.com/abc/profile/cdkts.json
|
||||
|
||||
{
|
||||
"$id": "https://schema.tiararodney.com/abc/profile/cdkts.schema.json",
|
||||
"title": "ABC CDK TypeScript Profile",
|
||||
"allOf": [
|
||||
{ "$ref": "https://abc-spec.org/schema/abc-schema.json" }
|
||||
],
|
||||
"properties": {
|
||||
"cdkts": {
|
||||
"type": "object",
|
||||
"description": "CDKTS-specific rules and metadata."
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
How The Schema is Consumed
|
||||
==========================
|
||||
|
||||
#. **Generate ABC structures from natural language**
|
||||
The schema defines the allowed constructs and relationships.
|
||||
#. **Validate the architecture**
|
||||
The schema + validation rules ensure correctness.
|
||||
#. **Compile into IaC**
|
||||
Profiles map the schema to CDK, Terraform, Pulumi, etc.
|
||||
#. **Refactor architectures**
|
||||
Agents can safely transform the schema because the rules are explicit.
|
||||
#. **Generate documentation**
|
||||
The schema is a perfect source for diagrams and docs.
|
||||
Loading…
Add table
Add a link
Reference in a new issue