02 Architecture

백엔드 아키텍처

한 문장 설명

FOWOCO 백엔드는 AI 모델이 아니라 AI 결과를 안전한 HR Workflow로 연결하는 업무 운영 서버입니다.

배포 구조

flowchart LR
  C["React Client"] -->|"JWT / HTTPS"| B["Spring Boot Backend"]
  B --> DB["PostgreSQL"]
  B --> FS["Local / S3 Compatible Storage"]
  B --> AA["AI Adapter"]
  AA --> LLM["External LLM API / Cloud Endpoint"]
  K["Context Pack / Workflow Catalog"] --> AA

Loading

개발 중에는 AI Adapter의 Provider만 LM Studio 호환 구현으로 바꿀 수 있습니다. 최종 데모는 외부 LLM이나 클라우드 Endpoint를 사용합니다.

요청 처리 책임

구성요소	책임	하지 않는 일
Controller	HTTP 입력·인증 정보 수신, 응답 변환	비즈니스 상태 임의 변경
Application Service	유스케이스 순서와 Transaction 관리	Provider별 HTTP 세부 구현
Domain	권한·상태 전이·업무 규칙	DB·외부 API 직접 호출
Repository	company_id가 포함된 저장·조회	다른 사업장 데이터 혼합
AI Adapter	비식별화·모델 호출·Schema 검증	업무 승인·근로자 발송
Workflow Service	허용 상태 전이와 완료 조건 검사	법률·노무 최종 판단
Audit Service	Actor·행동·대상·시각 기록	Secret·민감 원문 저장

권장 패키지

com.fowoco.server
├── common          # 오류, 시간, ID, 공통 보안 도구
├── auth            # 로그인, JWT, Refresh Token, 역할
├── company         # 사업장 경계
├── worker          # 근로자와 서류 메타데이터
├── document        # 파일 저장, 문서함, 준비도
├── task            # 업무카드와 Workflow
├── ai              # Adapter, Provider, Schema, 호출 로그
├── publiclink      # 근로자 보안 링크와 응답
├── imports         # CSV/XLSX 매핑, 검증, 선택 등록
├── dashboard       # 오늘 업무 조회 모델
├── settings        # 사업장 운영 정책
└── audit           # 승인과 감사 이벤트

각 기능 패키지 안에서는 필요할 때 다음 역할을 분리합니다.

api              Controller, Request/Response DTO
application      유스케이스 Service
domain           Entity, Value Object, 정책
infrastructure   JPA, 외부 API, 파일 저장 구현

MVP에서는 코드가 없는 계층을 미리 만들지 않습니다. 외부 시스템 경계와 복잡한 업무 규칙이 생길 때 분리합니다.

핵심 요청 흐름: tasks/analyze

sequenceDiagram
  actor HR
  participant API as TaskController
  participant TS as TaskService
  participant DB as PostgreSQL
  participant AA as AI Adapter
  participant LLM as External LLM

  HR->>API: POST /tasks/analyze
  API->>TS: 인증 사용자 + 원문
  TS->>DB: 회사·근로자 Context 조회
  TS->>AA: 최소화된 분석 Command
  AA->>AA: 민감정보 제거 + 버전 주입
  AA->>LLM: Structured Output 요청
  LLM-->>AA: JSON 후보
  AA->>AA: Schema·핵심값·신뢰도 검증
  AA-->>TS: 검증 결과 또는 안전한 오류
  TS->>DB: TaskAnalysisCandidate + AiInvocation 저장
  TS-->>API: NEEDS_INFO / READY_FOR_REVIEW 후보
  API-->>HR: 검토할 후보 목록

Loading

HR이 후보를 고른 뒤 POST /task-analyses/{analysisId}/confirm을 호출해야 실제 Task가 생성됩니다. 분석 성공만으로 업무가 생성·승인·발송되지는 않습니다.

의존성 규칙

• Controller가 JPA Repository나 외부 LLM을 직접 호출하지 않습니다.
• TaskService가 OpenAI/Gemini 같은 특정 Provider DTO를 알지 않습니다.
• 공개 Worker Link API가 내부 HR 응답 DTO를 재사용하지 않습니다.
• AI 입력 DTO에 민감정보 필드를 만들지 않습니다.
• 상태 변경은 TaskWorkflowService를 우회하지 않습니다.
• 중요한 변경과 AuditLog는 같은 Transaction 경계를 사용합니다.

버전 관리 단위

모든 AI 호출에는 다음 배포 단위를 기록합니다.

필드	예시
backend_version	0.1.0 또는 Git SHA
agent_version	task-agent-v1
model_provider	openai
model_name	배포에서 선택한 모델명
model_version	Provider가 제공하는 버전 또는 별칭
prompt_version	task-analysis-v1
context_pack_version	context-v0.2
workflow_catalog_version	workflow-v1

이 기록은 향후 Blue/Green Agent 전환과 즉시 롤백의 기반이 됩니다. MVP에서는 Router를 구현하지 않아도 필드는 지금부터 저장합니다.

관련 이슈

• #3 개발 기반
• #6 Workflow
• #8 AI Adapter
• #11 승인·감사
• #13 파일·문서 준비도
• #14 파일 가져오기