[Architecture] 저장소 경계·모듈·API·이벤트 계약 ADR 작성 #23

완료 기록

• 2026-07-23: ADR-0001~0003을 Accepted로 확정하고 PR #36으로 main에 병합했습니다.
• 후속 기능은 해당 ADR을 현재 구현 기준으로 사용합니다.

한 줄 목표

기능 구현 전에 저장소 책임, Server 모듈, API 계약 원본, 상태, 이벤트, 오류와 retry 소유권을 ADR로 고정합니다.

먼저 결정할 이유

현재 도메인 구현 전이라 경계를 가장 저렴하게 고칠 수 있습니다. 이 ADR 없이 진행하면 Server와 ai가 Prompt/Provider를, Server와 knowledge가 Workflow 규칙을 중복 구현할 위험이 큽니다.

저장소 계약 소유권

계약 변경 순서: owner repo PR → contract test → versioned release → consumer pin update → Notion/Wiki mirror sync입니다.

Server 모듈 초안

고정할 결정

• /api/v1 외부 API, /internal/v1 AI Runtime API, /health 운영 경로
• /tasks/analyze 폐기, /ai-runs canonical resource
• /ai-runs/{id}/candidate-decisions와 Task 승인 분리
• AiRun 기술 상태와 분석 outcome 분리
• Knowledge Catalog와 Server Task Workflow 구분
• Domain Event envelope·Transaction boundary·Outbox 대안
• Server durable retry와 AI provider-attempt retry budget 분리
• common Error contract와 feature별 Error Code
• PII allow-list, log 금지값, service-to-service auth
• version compatibility matrix와 AiRun 기록 필드
• Flyway migration 번호·병합 순서

Version compatibility 최소 필드

• backendVersion, agentVersion, modelProvider, modelName, modelVersion
• promptVersion, contextPackVersion, workflowCatalogVersion
• contractVersion, knowledgeVersion, requestId, attemptId
• latencyMs, providerAttemptCount, parsing/validation error code

완료 조건

• 새 팀원이 “이 변경은 어느 repo와 module에 넣는가”를 표로 판단할 수 있습니다.
• Server 코드에 Prompt Builder와 Provider SDK를 둘 수 없다는 ArchUnit rule 또는 리뷰 기준이 있습니다.
• AI/Knowledge가 운영 DB·Task 상태·승인 API에 접근하지 않습니다.
• 같은 의미의 중복 API·상태·Schema가 없습니다.
• [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11, [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24, #25와 OpenAPI/Wiki가 ADR 용어를 사용합니다.

이번 이슈에서 하지 않는 것

• 전체 기능 구현, Provider 선택, 모델 성능 평가
• Kafka/Kubernetes/범용 Workflow DSL

관계

• 선행: [Foundation] Spring Boot 개발·검증 기반 정리 #3
• 후속: [Task Workflow] 업무카드·체크리스트·상태 전이 구현 #6, [AI Integration] AiRuntimeClient·계약 검증·장애 격리 구현 #8, [Approval & Audit] 승인·반려·외부제출·증빙·완료·감사 로그 구현 #11, [AI Run] 비동기 실행 상태·재시도·멱등성 구현 #24, [Reliability] 이벤트 유실 방지·재처리 기반 구현 #25
• Parent: [EPIC] FOWOCO Server Roadmap · Controlled AI Workflow MVP #2