stack-diagram (스택 다이어그램)

stack-diagram (스택 다이어그램)은(는) 무엇을 하나요?

실제 로고가 있는 흰 타일, 라벨이 붙은 그룹 상자(클라우드 공급업체 VPC 다이어그램 스타일), 모노스페이스 라벨이 있는 직교 화살표, 시원한 그래프 용지 배경을 사용한 엔지니어링 도면 스타일의 아키텍처 다이어그램을 생성합니다. 하나의 자체 포함된 HTML 파일이 소스 오브 트루스이며, PNG / TSX / 아티팩트는 이 파일에서 파생됩니다.

요구 사항

• Python 3.9+ (fetch_icons.py, build.py, share.py에는 표준 라이브러리만 필요)
• 아이콘 소스에 대한 네트워크 액세스 (svgl.app, raw.githubusercontent.com, cdn.jsdelivr.net, aws.amazon.com 및 d1.awsstatic.com(AWS 아이콘용), services.google.com(Google Cloud 아이콘용), learn.microsoft.com 및 arch-center.azureedge.net(Azure 아이콘용), 그리고 name=URL의 브랜드 자체 사이트 또는 저장소)
• render_png.py용 Playwright + Chromium: pip install playwright && python3 -m playwright install --with-deps chromium

워크플로

1. 콘텐츠(노드, 그룹, 엣지) 확정
2. 아이콘 가져오기 — scripts/fetch_icons.py
3. 좌표 계획 — references/geometry.md 참조
4. assets/template.html에서 HTML 빌드 — scripts/build.py
5. PNG를 렌더링하고 전달 전에 확인
6. 요청된 형식으로 전달
7. 선택적으로 공개 갤러리에 공유

1단계 — 콘텐츠

사용자의 기술/서비스 목록에서 다음을 결정:

• 노드: 각 기술 = 하나의 노드 (이름 + 짧은 소문자 역할, 예: http server, sqlite db)
• 그룹: 런타임, 공급업체 또는 저장소를 공유하는 것들 주위에 상자 그리기 (예: 클라우드 공급자 상자 안에 런타임 상자; 도구용 모노레포 상자). 한 단계 중첩은 괜찮지만, 더 깊게는 복잡해집니다. 그룹 라벨은 브랜드의 고유 대소문자(GitHub, npm)로 작성; 템플릿은 그대로 표시합니다.
• 엣지, 세 가지 종류:
  • 강조색 실선 = 기본 요청/데이터 흐름 (하나의 연속 경로가 가장 좋음)
  • 중립 실선 = 보조 내부 연결
  • 중립 점선 = 개발 시간/배포 시간 관계(CI, git 후크, IaC 배포)

사용자가 도구의 평면 목록만 제공한 경우, 도구의 특성에서 합리적인 그룹과 흐름을 유추하고, 도구가 양쪽 모두에 대해 다이어그램이 잘못될 정도로 모호한 경우에만 질문합니다.

2단계 — 아이콘

python3 scripts/fetch_icons.py <icons-dir> tanstack hono drizzle "betterauth:better-auth" "orpc=https://orpc.unnoq.com/logo.webp"
python3 scripts/fetch_icons.py <icons-dir> "aws:aws/AWS-Cloud-logo" "vpc:aws/vpc" "fargate:aws/fargate" "s3:aws/s3"
python3 scripts/fetch_icons.py <icons-dir> "gcp:google-cloud" "run:gcp/cloud-run" "lb:gcp/load-balancing" "sql:gcp/cloud-sql"
python3 scripts/fetch_icons.py <icons-dir> "azure:azure/Azure-A" "app:azure/app-service" "vnet:azure/vnet" "sql:azure/sql-database"
python3 scripts/fetch_icons.py <icons-dir> "k8s:kubernetes" "ing:k8s/ingress" "svc:k8s/service" "deploy:k8s/deployment" "pod:k8s/pod"

사양 형식: name (슬러그로 사용되는 이름), name:slug (다른 슬러그), name=URL (명시적 URL), name:aws/<Name> (공식 AWS 아이콘), name:gcp/<Product> (공식 Google Cloud 아이콘), name:azure/<Name> (공식 Azure 아이콘), name:k8s/<Resource> (공식 Kubernetes 아이콘). 스크립트는 svgl → devicon → gilbarbara/logos 순서로 시도하고, 파일과 manifest.json을 쓰며, 채우기가 흰색인 아이콘을 표시합니다. svgl(svgl.app)이 첫 번째인 이유는 최신 개발 브랜드(TanStack, Better Auth, Hono...)의 현재 공식 마크를 가지고 있기 때문입니다. 로고에 밝음/어두움 버전이 있는 경우 밝은 버전은 <name>이 되고(타일은 두 테마 모두 흰색), 어두운 버전은 그룹 라벨용으로 <name>_dark로 저장됩니다. svgl은 정확한 제목으로만 일치하므로, 실패하면 다음으로 넘어갑니다. 또한 API는 wordmark 변형을 제공하지만, 가끔 넓은 그룹 라벨에 유용할 뿐 타일에는 사용하지 않습니다.

메커니즘보다 더 중요한 규칙:

• 로고를 다시 색칠하지 마십시오. 사용자가 알아차립니다. 로고가 흰색이거나 흰색 타일에 비해 너무 밝으면, 채우기를 건드리는 대신 어두운 타일(tile dark 클래스)에 놓으십시오. 매니페스트의 white_fill 플래그는 휴리스틱입니다. 흰색 채우기는 색상이 있는 마크(tRPC, Ubuntu)의 내부 세부 사항일 수 있으므로, 어두운 타일을 사용하기 전에 SVG를 살펴보십시오.
• 공식 마크만 사용하십시오. simple-icons는 의도적으로 소스에서 제외되었습니다. 그 글리프는 단색 다시 그리기이며, 사용자는 그것들을 보자마자 잘못되었다고 말합니다. 모든 소스가 실패(FAIL)하면, 공식 파일을 찾아 name=URL로 전달하십시오. 프로젝트의 저장소(루트 logo*.svg, docs/, assets/, public/)와 사이트(/logo.svg, /favicon.svg, /images/logo.svg)를 확인하십시오. 일부 마크는 저장소에만 있습니다(Lefthook의 마크는 evilmartians/lefthook 루트의 logo_sign.svg).
• 추상적인 개념은 픽토그램을 사용하고 텍스트를 사용하지 않습니다. "dev environment", "cron", "queue", "cache", "webhook receiver"와 같은 노드에는 브랜드가 없습니다. name:lucide/<icon>을 통해 Lucide 라인 아이콘을 사용하십시오(예: devenv:lucide/terminal, cron:lucide/clock; lucide.dev/icons에서 검색). 타일 안에 텍스트나 이모지를 사용하지 마십시오.
• 공급업체 하위 제품(Cloudflare D1/R2/KV...)은 일반적으로 별도의 로고가 없습니다. 타일에 공급업체 로고를 재사용하고 노드 이름이 구분을 제공하게 하십시오("Cloudflare D1" / "sqlite db").
• AWS는 AWS 자체 아이콘을 사용합니다. 각 서비스에는 하나씩 있습니다. name:aws/<Name>으로 가져오고, 런타임에 AWS 공식 아이콘 패키지에서 읽습니다(예: lambda:aws/lambda, aws:aws/AWS-Cloud-logo, s3:aws/s3). AWS- / Amazon- 접두사는 선택 사항이며, 일반적인 약어가 작동합니다(s3, sqs, sns, ses, ecs, eks, ecr, elb, alb, nlb, iam, kms, msk, vpc). 실패하면 모든 이름이 출력됩니다. 슬러그 aws, amazonwebservices 및 aws-*는 동일한 패키지로 이동하며, 패키지에 없는 것은 타사 복사본으로 대체되지 않고 FAIL이 됩니다. 서비스에는 항상 aws/ 접두사를 사용하십시오. dynamodb만 사용하면 여전히 타사 체인을 거칩니다. 패키지와 느슨한 아이콘 파일을 저장소 밖에 보관하십시오. AWS는 다이어그램에서 아이콘을 허용하며, 재배포는 확인되지 않았습니다.
• AWS 영역은 AWS 자체 그리기 규칙을 따릅니다. 서비스 아이콘은 자체 정사각형을 가지며 밝은 바탕과 어두운 바탕에서 작동하므로 tile bare를 사용하십시오. 흰색 타일은 프레임만 두 배로 만듭니다. 그 안의 사람 및 일반 노드는 tile bare res에서 AWS 일반 아이콘(user:aws/General-User; 또한 General-Users, General-Client, General-Internet, General-Server)을 템플릿의 lt/dk 쌍과 함께 사용합니다. 그룹은 AWS Cloud의 경우 group aws를 사용하고(라벨에 aws:aws/AWS-Cloud-logo 포함), 나머지는 region, az, vpc, private 또는 public을 사용합니다. 정사각형 모서리, 외곽선만, 라벨은 잉크로, 공급업체 색조 없음, 모서리에 14px 대신 30px 아이콘을 깔끔하게 배치합니다. VPC 내부에서는 분할을 알거나 안전하게 추론할 수 있는 경우(인터넷 연결 로드 밸런서는 공용, 앱 서버와 데이터베이스는 비공개) 공용 및 개인 서브넷을 표시하십시오. 평면 VPC는 AWS 사용자가 가장 먼저 알아차리는 것입니다. 내부 엣지는 하나의 색상과 열린 화살촉을 사용합니다: <path class="aws" ... marker-end="url(#open)"/>, 개발/배포에는 aws dash, 일반 .el 라벨, 그리고 이에 대한 범례는 없습니다. 노드 이름은 Amazon S3 / AWS Fargate로 지정하고, S3 / Fargate로 지정하지 마십시오. ALB와 같은 약식은 역할 줄에 전체 이름(Elastic Load Balancing) 아래에 넣습니다. 이름은 두 줄을 차지할 수 있지만, Amazon / AWS는 첫 번째 단어 줄에 남아 있어야 합니다. 접두사 바로 뒤에 줄바꿈이 발생하면 해당 노드를 넓히십시오(left:<centerX-76>px; width:152px).
• Google Cloud는 Google 자체 아이콘을 사용합니다. name:gcp/<Product>로 가져오고, 런타임에 Google 공식 패키지에서 읽습니다(예: run:gcp/cloud-run, lb:gcp/load-balancing, memorystore:gcp/memorystore). 핵심 제품만 자체 아이콘을 가지고 있습니다(Cloud Run, Cloud SQL, Cloud Storage, BigQuery, GKE, Compute Engine, Vertex AI...). 다른 모든 제품은 Google 가이드에 지정된 대로 해당 카테고리의 아이콘을 사용합니다. Cloud Load Balancing과 Cloud CDN은 모두 Networking을 얻습니다. Memorystore와 Firestore는 모두 Databases를 얻습니다. 제품 이름을 쓰면 스크립트가 아이콘을 선택합니다. Cloud / Google 접두사는 선택 사항이며, 일부 약식이 작동합니다(vpc, iam, kms, iap, gce, gcs). 실패하면 모든 이름이 출력됩니다. gcp/storage는 Storage 카테고리입니다. Cloud Storage는 gcp/cloud-storage입니다. 슬러그 gcp-* 및 google-cloud-*는 동일한 패키지로 이동하며, 패키지에 없는 것은 타사 복사본으로 대체되지 않고 FAIL이 됩니다. 이러한 복사본은 사용되지 않는 육각형 아이콘으로, Google은 사용하지 말라고 말합니다. 제품에는 항상 gcp/ 접두사를 사용하십시오. bigquery만 사용하면 여전히 타사 체인을 거칩니다. gcp:google-cloud는 그룹 라벨용 Google Cloud 마크입니다. Gemini와 Firebase는 패키지에 없습니다. gemini와 firebase를 그대로 사용하십시오. 패키지와 느슨한 아이콘 파일을 저장소 밖에 보관하십시오. Google은 다이어그램과 문서를 위해 아이콘을 제공하며, 재배포는 확인되지 않았습니다.
• Google Cloud 다이어그램은 Google 그룹과 함께 일반 스타일을 유지합니다. Google 자체 다이어그램(단색 파란색 패널, 수평 카드)은 의도적으로 복사되지 않았습니다. 아이콘은 일반 흰색 타일에 표시되며, 엣지와 범례는 평소와 같이 유지됩니다. 그룹은 Google Cloud의 경우 템플릿의 group gcp를 사용하고(라벨에 gcp:google-cloud 포함), vpc, region, subnet 또는 zone을 추가합니다. VPC는 글로벌하고 서브넷은 리전이므로, 리전을 VPC 내부에 배치하고 VPC를 리전 내부에 배치하지 마십시오. 글로벌 및 서버리스 서비스(외부 로드 밸런서, Cloud Storage, Cloud Run)는 VPC 외부에 유지됩니다. 아이콘이 공유되므로 항상 제품의 전체 이름(Cloud Load Balancing, LB 아님)을 쓰고, 이름이 줄바꿈될 노드를 넓히십시오(left:<centerX-76>px; width:152px).
• Azure는 Microsoft 자체 아이콘을 사용합니다. 각 서비스에는 하나씩 있습니다. name:azure/<Name>으로 가져오고, 런타임에 Microsoft 공식 패키지에서 읽습니다(예: app:azure/app-service, azure:azure/Azure-A, vault:azure/key-vault). Azure- / Microsoft- 접두사와 복수형 s는 선택 사항이며, 일반적인 약식이 작동합니다(aks, vm, vnet, nsg, waf, blob, cosmos, redis, postgres, functions, front-door, apim, ai-search). 실패하면 모든 이름이 출력됩니다. 슬러그 azure, microsoft-azure 및 azure-*는 동일한 패키지로 이동하며, 패키지에 없는 것은 타사 복사본으로 대체되지 않고 FAIL이 됩니다. 서비스에는 항상 azure/ 접두사를 사용하십시오. cosmos만 사용하면 여전히 타사 체인을 거칩니다. Microsoft Entra ID에는 별도의 아이콘 세트가 있습니다. 공식 파일을 name=URL로 전달하십시오. Microsoft는 아키텍처 다이어그램, 교육 자료 및 문서에서만 이러한 아이콘을 사용하도록 허용합니다. 절대 자르거나, 뒤집거나, 회전시키거나, 모양을 바꾸지 말고, 나타내는 Microsoft 서비스에만 사용하고, 패키지와 느슨한 아이콘 파일을 저장소 밖에 보관하십시오.
• Azure 다이어그램은 Microsoft 그룹 색상과 함께 일반 스타일을 유지합니다. Microsoft 자체 다이어그램은 의도적으로 복사되지 않았습니다. 아이콘은 일반 흰색 타일에 표시되며, 엣지와 범례는 평소와 같이 유지됩니다. 그룹은 Azure의 경우 템플릿의 group azure를 사용하고(라벨에 azure:azure/Azure-A 포함), rg, region, vnet, subnet 또는 zone을 추가하며, vnet 또는 subnet 라벨은 해당 아이콘(vnet:azure/vnet, subnet:azure/subnet)을 전달합니다. VNet은 하나의 리전에 속하므로 리전 내부에 배치됩니다. Front Door와 같은 글로벌 서비스는 리전 외부에 유지됩니다. App Service는 App Service Environment에서 실행되지 않는 한 VNet 외부에 있으며, 개인 엔드포인트를 통해 도달하는 PaaS 서비스는 역할로 private endpoint를 사용하여 내부에 배치될 수 있습니다. Microsoft는 각 아이콘 옆에 서비스 전체 이름(Azure SQL Database, SQL 아님)을 요구하므로, 이름이 줄바꿈될 노드를 넓히십시오(left:<centerX-76>px; width:152px).
• Kubernetes는 공식 커뮤니티 아이콘을 사용합니다. name:k8s/<Resource>로 가져오고, 공식 kubernetes/community 아이콘 세트에서 읽습니다(예: pod:k8s/pod, deploy:k8s/deployment, svc:k8s/service, ing:k8s/ingress, cm:k8s/configmap, secret:k8s/secret, node:k8s/node, api:k8s/kube-apiserver). 아이콘은 리소스 및 인프라에 대해 레이블이 없는 변형을 사용하여 다이어그램 규모에서 글리프를 깔끔하고 산만하지 않게 유지하고, 제어 평면 구성 요소에 대해 레이블이 있는 변형을 사용합니다. 일반적인 짧은 이름과 복수형이 작동합니다(svc/service/services, deploy/deployment/deployments, po/pod/pods, cm/configmap/configmaps, sts/statefulset, ds/daemonset, node/nodes 등). 실패하면 사용 가능한 이름이 출력됩니다. 슬러그 k8s, kubernetes 및 k8s/k8s는 체인을 통해 공식 Kubernetes 휠 로고를 제공합니다.
• Kubernetes 다이어그램은 기본적으로 일반 스타일을 유지합니다. 아이콘은 일반 흰색 타일에 표시되어 스택의 다른 기술(NGINX, cert-manager, 외부 데이터베이스 또는 클라우드 로드 밸런서 등)과 통합되고 그래프 용지 배경에 일관된 입체감과 대비를 제공합니다. 최소한의 독립형 글리프의 경우 tile bare도 지원됩니다. 그룹은 표준 그룹(cluster, namespace, node, pod)을 사용합니다. 다이어그램 바닥글에 Kubernetes 아이콘 세트 크레딧을 표시합니다.
• 공급업체의 규칙은 자체 영역에만 적용됩니다. 다이어그램에 다른 것이 표시되지 않더라도 AWS, Google Cloud, Azure 및 Kubernetes 규칙은 해당 공급업체 그룹 내부에만 적용됩니다. 그 외부의 모든 것(예: 옆에 있는 사용자 또는 그 안으로 교차하는 엣지)은 일반 타일, 그룹, 엣지 및 범례를 유지합니다.
• 비브랜드 노드(사용자, 브라우저, 인터넷, 장치, 베어메탈 서버): assets/generic/에서 글리프를 노드 이름으로 아이콘 디렉토리에 복사하거나 name:lucide/<icon>을 사용하십시오. 이모지를 사용하지 마십시오. 이것들은 브랜드 로고가 아니므로 다이어그램의 잉크 색상으로 색조를 입히는 것은 괜찮습니다(가져오기 스크립트는 Lucide에 대해 자동으로 수행합니다).
• 그룹 라벨 아이콘은 14px로 렌더링됩니다. 정사각형 글리프 마크가 필요합니다. 워드마크와 넓은 로고는 해당 크기에서 흐려집니다. 기본 아이콘이 워드마크인 경우 라벨용으로 브랜드의 정사각형 아이콘을 별도로 가져오십시오(svgl에 일반적으로 있음, 그렇지 않으면 프로젝트 자체 아이콘 또는 파비콘 파일).
• 그룹 라벨은 흰색 타일이 아닌 그룹 색조 위에 표시되므로, 어두운 테마에서 검은색 부분이 있는 마크는 그곳에서 사라집니다. fetch_icons.py가 <name>_dark를 저장한 경우 라벨에 템플릿의 lt/dk 쌍을 사용하십시오. 어두운 변형이 없고 마크에 검은색 부분이 있는 경우 라벨에 plate 클래스를 추가하십시오.