Files

T

Antigravity Agent 504fd5fb42 [G1-Sync] Manual knowledge update

2026-05-10 22:08:15 +09:00

7.1 KiB

Raw Blame History

id, title, category, status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, verification_status, tags, raw_sources, last_reinforced, github_commit, tech_stack

title

Architecture Description (아키텍처 명세)

매 한 줄

"매 architecture description 은 system 의 multiple stakeholder concern 을 multiple view 로 documenting". ISO/IEC/IEEE 42010 standard 기반 — 매 stakeholder, concern, viewpoint, view, model 의 conceptual chain. 매 modern practice 는 4+1 (Kruchten) → C4 (Brown) → arc42 (Starke) → DAR (Decision Records) 의 layered combination.

매 핵심

매 ISO/IEC/IEEE 42010 framework

Stakeholder: dev, ops, security, PM, customer — 매 다른 concern.
Concern: performance, security, deployability, cost, regulatory.
Viewpoint: concern 의 lens (e.g., "security viewpoint", "deployment viewpoint").
View: viewpoint 적용 결과의 specific artifact.
Model: view 안의 box-and-line / sequence / state diagram.

매 4+1 view (Kruchten 1995, still relevant)

Logical view: domain model, class, package — dev concern.
Process view: runtime behavior, threading, concurrency — perf concern.
Development view: module, layer, build — dev productivity.
Physical view: deployment topology — ops concern.
+1 Scenario: use cases tying 4 views together.

매 C4 model (Simon Brown, modern default)

Context (L1): system + external actor/system — non-technical stakeholder 용.
Container (L2): deployable unit (web app, API, DB) — tech overview.
Component (L3): container 내부 module — dev 용.
Code (L4, optional): class diagram — auto-gen, rarely manual.

💻 패턴

Structurizr DSL (modern C4 standard, 2026)

workspace "BankingApp" {
    model {
        customer = person "Customer" "A bank customer"
        bankingSystem = softwareSystem "Internet Banking" {
            webApp = container "Web App" "React SPA" "TypeScript/React"
            api = container "API" "REST backend" "Kotlin/Spring"
            db = container "Database" "Customer + tx data" "PostgreSQL 16"
            webApp -> api "Calls" "HTTPS/JSON"
            api -> db "Reads/writes" "JDBC"
        }
        customer -> webApp "Uses" "HTTPS"
    }
    views {
        systemContext bankingSystem { include * autoLayout }
        container bankingSystem { include * autoLayout }
        theme default
    }
}

arc42 template skeleton (Markdown, 12 sections)

# 1. Introduction & Goals
## 1.1 Requirements Overview
## 1.2 Quality Goals (top 3-5)
## 1.3 Stakeholders

# 2. Architecture Constraints
# 3. Context & Scope (C4 L1 here)
# 4. Solution Strategy
# 5. Building Block View (C4 L2/L3)
# 6. Runtime View (sequence / activity)
# 7. Deployment View
# 8. Crosscutting Concepts (security, logging, i18n)
# 9. Architecture Decisions (link to ADRs)
# 10. Quality Requirements (scenarios)
# 11. Risks & Technical Debt
# 12. Glossary

ADR (Architecture Decision Record, Michael Nygard format)

# ADR-0042: Use PostgreSQL over MongoDB for tx store

## Status
Accepted (2026-04-15) — supersedes ADR-0021.

## Context
Transactional integrity 의 critical. Document flexibility 의 secondary.
PostgreSQL 16 의 JSONB columns 의 hybrid 의 enable.

## Decision
PostgreSQL 16 with JSONB for flexible attributes.

## Consequences
+ ACID guarantees, mature tooling, strong ecosystem.
- Schema migrations more rigid than Mongo.
- Team needs PG expertise (training budget allocated).

Mermaid C4 diagram (lightweight, GitHub-native)

C4Context
  title System Context — Banking
  Person(customer, "Customer")
  System(banking, "Banking System", "Online banking")
  System_Ext(email, "Email System", "SMTP")
  Rel(customer, banking, "Uses", "HTTPS")
  Rel(banking, email, "Sends notifications", "SMTP")

Architecture-as-code: PlantUML C4 macro

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User")
System_Boundary(c1, "App") {
  Container(spa, "SPA", "React 19")
  Container(api, "API", "Kotlin/Ktor")
  ContainerDb(db, "DB", "PostgreSQL 16")
}
Rel(user, spa, "Uses", "HTTPS")
Rel(spa, api, "JSON/REST")
Rel(api, db, "JDBC")
@enduml

Quality scenario (ATAM-style, embeddable in AD)

scenario: "API survives 10x traffic spike"
source: External users
stimulus: Sudden 10x request burst
artifact: API container
environment: Production, normal ops
response: Auto-scale, no errors >0.1%
response_measure:
  - p99 latency < 800ms
  - error_rate < 0.1%
  - autoscale_lag < 60s

Living docs — auto-extract from code (jQAssistant + Structurizr)

# Generate Structurizr workspace from code annotations
./gradlew structurizrExport
structurizr-cli push -workspace workspace.dsl \
  -id $WORKSPACE_ID -key $API_KEY -secret $API_SECRET

매 결정 기준

상황	Approach
Greenfield, small-mid team	C4 + arc42 + ADR
Enterprise, regulatory	ISO 42010 strict + 4+1
OSS project	Mermaid C4 in README
Microservices, many teams	Structurizr DSL + ADR per service
Legacy reverse-engineered	Auto-gen (jQAssistant) + manual context

기본값: C4 (Structurizr DSL) + arc42 sections + ADR — 매 modern combination.

🔗 Graph

부모: Software Architecture · ISO-IEC-IEEE 42010
변형: 4+1 View Model · C4 Model · arc42
응용: Architecture Decision Records · Architecture_Diagramming_Standards · Architecture Review (아키텍처 및 설계 리뷰)
Adjacent: Architectural Views · Stakeholder Analysis

🤖 LLM 활용

언제: bootstrap arc42 template from a codebase scan, generate C4 Container diagrams from package structure, draft ADR Context/Consequences from PR descriptions. 언제 X: do not let an LLM author quality scenarios without measurable response criteria — vague AI-generated "should be fast" fails ATAM review.

❌ 안티패턴

Diagram-only AD: pictures without prose context — stakeholder cannot infer intent.
One-view-fits-all: single deployment diagram trying to satisfy security, perf, dev concerns simultaneously.
Stale Visio: AD frozen on day 1, drifts from implementation within 6 months.
Pseudo-UML: ad-hoc boxes labeled "UML" with no notation discipline.
Decision-less AD: structures documented without WHY — readers cannot evaluate tradeoffs.

🧪 검증 / 중복

Verified (ISO/IEC/IEEE 42010:2022, Kruchten 1995, Brown C4 spec, Starke arc42 v8.2).
신뢰도 A.

🕓 Changelog

날짜	변경
2026-05-08	Phase 1
2026-05-10	Manual cleanup — full AD spec with C4/4+1/arc42/ADR patterns

7.1 KiB Raw Blame History