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

[hywznn]

완료 기록

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

한 줄 목표

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

먼저 결정할 이유

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

저장소 계약 소유권

계약	Owner	Consumer
Client/Public Worker OpenAPI	server	client
/internal/v1/analyses OpenAPI·Structured Output Schema	ai	server
Intent/Domain/Slot/Workflow ID·Catalog·Context Pack	knowledge	ai, 필요한 Server projection
AiRun·Task 상태와 command	server	client, audit

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

Server 모듈 초안

모듈	책임	금지 의존성
auth/company	JWT, role, actor, company boundary	AI Runtime 세부 구현
worker/document/file	최소 개인정보, document metadata, storage port	Task 상태 직접 변경
task/workflow	Task, checklist, command/guard, optimistic lock	Provider SDK
approval/audit	approval snapshot, evidence, immutable audit	민감 원문·token
workerlink	token lifecycle와 public action	HR 내부 메모 노출
airun	durable run, candidate persistence, idempotency, retry	Prompt·모델 선택
aiintegration	AiRuntimeClient, service auth, timeout, response revalidation	OpenAI/Gemini/LM Studio client
reliability	outbox/publication recovery	Kafka 도입

고정할 결정

• /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