02 Architecture

백엔드 아키텍처

한 문장 설명

FOWOCO 백엔드는 AI 모델이 아니라 AI 제안을 검증·승인·복구 가능한 HR Workflow로 연결하는 업무 운영 서버입니다.

목표 구조

flowchart LR
  C["React Client"] -->|"JWT / HTTPS"| B["Spring Boot Modular Monolith"]
  WL["Worker Link"] -->|"만료 Token"| B
  B --> DB["PostgreSQL"]
  B --> FS["Local / S3-compatible Storage"]
  B --> EP["Durable Event Publication"]
  EP --> B
  B --> AA["AI Adapter / Gateway"]
  AA --> LLM["External LLM / Cloud Endpoint"]
  K["Context Pack / Workflow Catalog"] --> AA
  B -. "trace / metric" .-> O["Logs · Micrometer · OpenTelemetry"]

Loading

개발에서는 AI Provider만 Fake 또는 LM Studio 호환 구현으로 바꿉니다. 최종 데모는 외부 LLM/Cloud Endpoint를 사용하며, Provider 장애가 일반 HR API 전체를 막지 않게 격리합니다.

먼저 고정하는 선택

주제	기본 방향	이유
배포 단위	하나의 Spring Boot 애플리케이션	현재 팀·트래픽에서 분산 시스템 운영비를 피함
코드 구조	package-by-feature 모듈러 모놀리스	업무 책임과 변경 범위를 쉽게 찾음
Spring Modulith	경계 검증·Event Publication Registry의 작은 호환성 spike 후 결정	이름만 보고 의존성을 추가하지 않음
대안	PostgreSQL Transactional Outbox	동일한 내부 event port를 유지하며 유실 방지
Broker	M3에서 Kafka/RabbitMQ 미사용	실제 처리량·팀 분리가 생길 때 도입
API 경로	카탈로그에는 base URL을 제외한 resource path 기록	/api를 문서마다 중복·혼용하지 않음

최종 근거와 선택하지 않은 대안은 #23 ADR에 기록합니다.

모듈 책임

모듈	책임	직접 하지 않는 일
common	오류, 시간, ID, 공통 보안·관측 도구	업무 규칙 소유
auth	로그인, JWT/Refresh, Role, Actor	근로자·Task 상태 변경
company	사업장 Context와 tenant 경계	Client의 company_id 신뢰
worker	근로자 최소정보와 근무 상태	파일 원본·AI 호출
document	문서 metadata, 저장 port, 준비도	승인·자동 발송
task	업무카드, checklist, 조회	Provider별 HTTP
workflow	명령, 상태 전이, guard, 완료 조건	법률·노무 최종 판단
notice	승인된 안내와 전달 준비	승인 전 내용 발송
ai	AI Run, Adapter, Provider, 검증 후보	Task 승인·Worker token 처리
publiclink	근로자 링크·응답·token 범위 문서	내부 HR 정보 노출
audit	승인 snapshot, immutable audit, timeline projection	민감 원문·Secret 저장
imports	CSV/XLSX mapping·validation·commit	M3 대표 흐름 차단
dashboard/settings	M4 조회·운영 정책	핵심 command 우회

각 모듈 안에서는 실제 복잡성이 생길 때만 api, application, domain, infrastructure 역할을 분리합니다. 코드 없는 빈 계층을 미리 만들지 않습니다.

요청 처리 책임

구성요소	책임	금지
Controller	HTTP·인증 Context 수신, DTO 변환	Repository 직접 호출·상태 setter
Application Service	유스케이스·Transaction·멱등성	Provider SDK 타입 노출
Domain/Workflow Service	전이·승인·완료 guard	DB·외부 API 직접 호출
Repository	tenant 범위 저장·조회·lock	company_id 없는 business query
Event Publisher/Handler	commit 이후 후속 처리·재처리	민감 payload·비멱등 side effect
AI Adapter	비식별화·Provider 호출·검증	자동 승인·발송
Audit Service	Actor·snapshot·변경 요약·trace	token·Prompt 전문 저장

핵심 흐름: 비동기 AI Run

sequenceDiagram
  actor HR
  participant API as AiRunController
  participant ORC as AiOrchestrationService
  participant DB as PostgreSQL
  participant EVT as Durable Event Handler
  participant AD as AiAdapter
  participant LLM as External LLM

  HR->>API: POST /ai-runs + Idempotency-Key
  API->>ORC: actor + tenant + 최소 입력
  ORC->>DB: AiRun(QUEUED) + publication 저장
  ORC-->>API: 202 runId / statusUrl
  API-->>HR: 즉시 응답
  EVT->>DB: 미처리 AiRunRequested 획득
  EVT->>ORC: RUNNING 전이
  ORC->>AD: 비식별 command + versions
  AD->>LLM: timeout이 있는 structured request
  LLM-->>AD: JSON
  AD->>AD: Schema·핵심값·PII 검증
  AD-->>ORC: 검증 결과 또는 명시적 실패
  ORC->>DB: VALIDATING → SUCCEEDED / NEEDS_REVIEW / FAILED
  HR->>API: GET /ai-runs/{runId}
  API-->>HR: 상태·후보·검토 사유
  HR->>API: POST /ai-runs/{runId}/confirm
  ORC->>DB: 선택 후보만 Task로 정확히 한 번 생성

Loading

HTTP 연결이 끊겨도 Run은 DB에 남습니다. 서버 재시작 뒤 미완료 publication을 다시 처리하며, 같은 key/event/confirm이 반복돼도 Run과 Task가 중복 생성되지 않아야 합니다.

Transaction과 Event 경계

1. 업무 상태와 “후속 처리가 필요하다”는 publication record를 같은 DB transaction에 저장합니다.
2. commit 뒤 handler가 처리합니다.
3. 실패하면 오류 코드·시도 횟수·다음 시각을 남기고 제한적으로 재시도합니다.
4. 서버 재시작 시 미완료 record를 찾아 재발행합니다.
5. consumer는 event_id와 unique constraint로 중복에 안전해야 합니다.
6. 영구 실패는 가짜 완료로 바꾸지 않고 담당자 검토와 수동 재처리를 제공합니다.

모듈 의존성 규칙

• task/workflow는 OpenAI·Gemini·LM Studio 타입을 알지 않습니다.
• ai는 Worker Link 원본 token과 승인 command를 직접 만들지 않습니다.
• 공개 Worker Link DTO는 내부 HR DTO를 재사용하지 않습니다.
• 상태 변경은 Workflow Service를 우회하지 않습니다.
• 중요 변경·승인 snapshot·Audit event는 한 transaction 경계에 둡니다.
• event handler는 다른 모듈 Entity를 직접 수정하지 않고 공개 command를 호출합니다.
• 관측 도구 장애는 핵심 business transaction을 실패시키지 않습니다.

Agent 배포 단위

필드	설명
backend_version	Server release 또는 Git SHA
agent_version	orchestration 규칙 버전
model_provider/name/version	호출 모델 식별
prompt_version	Prompt 계약 버전
context_pack_version	검증된 지식 묶음 버전
workflow_catalog_version	필수정보·상태·완료 기준 버전
request_id / trace_id	API부터 event·Provider까지 추적

MVP에서는 Blue/Green Router를 구현하지 않지만 이 값을 지금부터 저장해 재현과 롤백 근거를 만듭니다.

관련 이슈

• #23 Architecture ADR
• #6 Workflow
• #8 AI Adapter
• #11 승인·감사
• #24 비동기 AI Run
• #25 Event 유실 방지
• #26 관측성