Skip to content

Commit c117941

Browse files
EMaherEMaher
authored
Merge pull request #56 from Azure/copilot/add-architecture-information
docs: add high-level architecture diagram (Mermaid)
2 parents f60ab29 + c50e2c9 commit c117941

3 files changed

Lines changed: 141 additions & 0 deletions

File tree

‎.devcontainer/devcontainer.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
"vscode": {
1616
"settings": {
1717
"terminal.integrated.defaultProfile.linux": "bash",
18+
"git.autofetch": true,
1819
"editor.formatOnSave": true,
1920
"editor.defaultFormatter": "dbaeumer.vscode-eslint",
2021
"eslint.format.enable": true,
@@ -24,6 +25,7 @@
2425
},
2526
"extensions": [
2627
"dbaeumer.vscode-eslint",
28+
"bierner.markdown-mermaid",
2729
"ms-vscode.vscode-typescript-next",
2830
"vitest.explorer",
2931
"GitHub.vscode-pull-request-github",

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
|---|---|
77
| **Source code** | [github.com/Azure/apiops-cli](https://github.com/Azure/apiops-cli) |
88
| **Issues** | [GitHub Issues](https://github.com/Azure/apiops-cli/issues) |
9+
| **Architecture** | [docs/architecture.md](./docs/architecture.md) |
910

1011
## Getting started
1112

‎docs/architecture.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Architecture
2+
3+
## Overview
4+
5+
`apiops` implements a **configuration-as-code** workflow for Azure API Management. Configuration is extracted from a running APIM instance into version-controlled artifact files. Those files become the source of truth for publishing to one or more environments, driven by a CI/CD pipeline.
6+
7+
---
8+
9+
## Configuration-as-Code Workflow
10+
11+
The sequence diagram below shows how `apiops` fits into a typical team workflow, including all commands and affected resources:
12+
13+
```mermaid
14+
sequenceDiagram
15+
participant dev as Developer
16+
participant git as Repository<br/>(GitHub/<br/>Azure DevOps)
17+
participant ci as CI/CD Pipeline
18+
participant apim_src as Source<br/>API Management
19+
participant apim_dst as Target<br/>API Management
20+
21+
rect rgb(200, 220, 255)
22+
note over dev: Step 1: Initialize
23+
dev->>git: Command: apiops init
24+
git->>git: Create CI/CD workflow files<br/>(extract & publish pipelines)
25+
end
26+
27+
rect rgb(200, 255, 220)
28+
note over dev: Step 2: Extract Configuration
29+
dev->>ci: Run extract pipeline
30+
note over ci: Command: apiops extract
31+
ci->>apim_src: Read configuration
32+
apim_src-->>ci: Current APIM config
33+
ci->>git: Write to apim-artifacts/
34+
git->>dev: Show extracted changes
35+
end
36+
37+
rect rgb(255, 240, 200)
38+
note over dev: Step 3-4: Review & Merge
39+
dev->>git: Create Pull Request
40+
note over git: Code review & approval
41+
dev->>git: Merge to main branch
42+
end
43+
44+
rect rgb(255, 220, 220)
45+
note over ci: Step 5: Publish Configuration
46+
git->>ci: Trigger publish pipeline
47+
note over ci: Command: apiops publish
48+
ci->>git: Read apim-artifacts/
49+
git-->>ci: Artifact files
50+
ci->>apim_dst: Apply configuration to target
51+
apim_dst-->>ci: Updated successfully
52+
end
53+
```
54+
55+
| Step | Command | Affected Resources | Description |
56+
|------|---------|-------------------|-------------|
57+
| 1 | `apiops init` | Repository | Scaffolds the Git repository with CI/CD workflow files and an identity setup guide |
58+
| 2 | `apiops extract` | Source APIM, apim-artifacts/ | Reads the running APIM configuration and writes it to local artifact files |
59+
| 3-4 | — | Repository (PR & Merge) | Developer submits extracted artifact changes for review and approves merge |
60+
| 5 | `apiops publish` | apim-artifacts/, Target APIM | On merge, the publish workflow runs and applies artifact files to the target API Management instance |
61+
62+
---
63+
64+
## Component Architecture
65+
66+
The diagram below shows the internal structure of the `apiops` CLI:
67+
68+
```mermaid
69+
flowchart TB
70+
subgraph entrypoint["CLI Entry Point"]
71+
extract_cmd["extract"]
72+
publish_cmd["publish"]
73+
init_cmd["init"]
74+
end
75+
76+
subgraph services["Services"]
77+
direction TB
78+
extract_svc["Extract Service<br/>(parallel by <br/>dependency tier)"]
79+
filter_svc["Filter + Transitive Resolver"]
80+
81+
publish_svc["Publish Service<br/>(dependency-ordered <br/>PUT / DELETE)"]
82+
override_svc["Override Merger<br/>(per-environment config)"]
83+
git_svc["Git Diff Service<br/>(incremental publish)"]
84+
dry_svc["Dry-run Reporter"]
85+
86+
init_svc["Init Service<br/>(CI/CD scaffolding)"]
87+
end
88+
89+
subgraph clients["Clients"]
90+
apim_client["API Management REST Client"]
91+
store["Artifact Store"]
92+
end
93+
94+
subgraph auth["Authentication"]
95+
auth_pkg["@azure/identity"]
96+
end
97+
98+
subgraph external["External Systems"]
99+
azure_apim[("API Management")]
100+
local_files[("fa:fa-folder Artifact Files<br/>(Local Filesystem)")]
101+
git_repo[("fa:fa-github GitHub / Azure DevOps")]
102+
end
103+
104+
extract_cmd --> extract_svc
105+
publish_cmd --> publish_svc
106+
init_cmd --> init_svc
107+
108+
extract_svc --> filter_svc
109+
extract_svc --> apim_client
110+
extract_svc --> store
111+
112+
publish_svc --> override_svc
113+
publish_svc --> git_svc
114+
publish_svc --> dry_svc
115+
publish_svc --> apim_client
116+
publish_svc --> store
117+
118+
apim_client --> auth_pkg
119+
auth_pkg --> azure_apim
120+
store <--> local_files
121+
git_svc --> git_repo
122+
init_svc --> git_repo
123+
```
124+
125+
## Authentication
126+
127+
`apiops` uses [`DefaultAzureCredential`](https://learn.microsoft.com/javascript/api/%40azure/identity/defaultazurecredential?view=azure-node-latest) from the `@azure/identity` SDK.
128+
129+
For the up-to-date credential chain and authentication behavior, see Microsoft docs:
130+
131+
- [Credential chains in the Azure Identity library for JavaScript](https://learn.microsoft.com/azure/developer/javascript/sdk/authentication/credential-chains)
132+
- [Authenticate JavaScript apps to Azure services during local development](https://learn.microsoft.com/azure/developer/javascript/sdk/authentication/local-development-environment-service-principal)
133+
134+
GitHub Actions workflows generated by `apiops init` use OIDC federated credentials for Azure authentication, which means you do not need to store an Azure client secret for `azure/login@v2`.
135+
136+
However, the generated workflows still require GitHub Actions secret or environment values such as `AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_SUBSCRIPTION_ID`, and any APIM environment-specific secrets referenced by the workflow templates.
137+
138+
---

0 commit comments

Comments
 (0)