docs: 심사위원용 AI 아키텍처·코드 투어 정리

README.md

@@ -1,6 +1,7 @@
 # FOWOCO AI
 
 <p align="center">
+  <a href="https://github.com/fowoco/ai/actions/workflows/ci.yml"><img alt="AI CI" src="https://github.com/fowoco/ai/actions/workflows/ci.yml/badge.svg?branch=main"></a>
   <a href="https://github.com/fowoco/ai/actions/workflows/deploy.yml"><img alt="AI Deploy" src="https://github.com/fowoco/ai/actions/workflows/deploy.yml/badge.svg?branch=main"></a>
 </p>
 
@@ -25,6 +26,31 @@ E-9 외국인근로자를 고용한 사업장의 재계약·체류기간 연장
 환경변수를 설정하지 않은 선택 기능은 Stub 또는 명시적인 `503`으로 동작합니다.
 따라서 “코드가 존재함”과 “실제 Provider가 활성화됨”을 구분해 확인해야 합니다.
 
+## 왜 이렇게 설계했나요?
+
+| 선택 | 프로젝트에서 필요했던 이유 |
+| --- | --- |
+| BERT → Guardrail → A.X | 반복적인 단일 Intent는 빠르게 처리하고, 경계·복합 발화만 더 큰 모델로 보완하기 위해서입니다. |
+| PLAN → ANALYZE 분리 | AI가 DB를 직접 조회하지 않고 필요한 field key만 요청한 뒤, Server가 권한을 검사해 Context를 보충하기 위해서입니다. |
+| LangGraph 상태 흐름 | 누락 정보, OCR, 근로자 안내, 문서 생성 분기를 코드와 테스트에서 명시적으로 추적하기 위해서입니다. |
+| 결정론적 문서 Tool | LLM이 HWP/HWPX 구조를 임의로 수정하지 않고 승인된 템플릿과 field map만 사용하게 하기 위해서입니다. |
+| Human-in-the-loop | 번역·OCR·문서 결과가 불확실하면 자동 발송하지 않고 HR 검토 상태로 되돌리기 위해서입니다. |
+
+## 5분 코드 투어
+
+심사·리뷰 시 아래 순서로 보면 전체 구현을 가장 빠르게 확인할 수 있습니다.
+
+| 순서 | 확인할 내용 | 대표 코드·테스트 |
+| --- | --- | --- |
+| 1 | FastAPI 진입점과 API 경계 | [`app/main.py`](app/main.py), [`app/api/router.py`](app/api/router.py), [`tests/api`](tests/api) |
+| 2 | PLAN·ANALYZE와 Intent 결정 재사용 | [`app/agents/pipeline.py`](app/agents/pipeline.py), [`app/agents/intent`](app/agents/intent), [`tests/agents/test_intent_hybrid.py`](tests/agents/test_intent_hybrid.py) |
+| 3 | Renewal Agent 상태·분기 | [`app/agents/workflow_graph/graph.py`](app/agents/workflow_graph/graph.py), [`app/agents/workflow_graph/supervisor.py`](app/agents/workflow_graph/supervisor.py), [`tests/agents/test_workflow_graph.py`](tests/agents/test_workflow_graph.py) |
+| 4 | Tool 구현과 실패 격리 | [`app/ocr`](app/ocr), [`app/agents/language`](app/agents/language), [`app/documents`](app/documents) |
+| 5 | Server–AI 계약과 대표 응답 | [`docs/analyses-contract.md`](docs/analyses-contract.md), [`docs/workflows-contract.md`](docs/workflows-contract.md), [`examples`](examples) |
+
+설계와 코드 관계를 더 자세히 보려면 [Architecture & Code Tour](docs/architecture.md),
+문서 전체 분류는 [Documentation Index](docs/README.md)를 확인합니다.
+
 ## 저장소 경계
 
 FOWOCO는 모델이 업무 시스템을 직접 조작하지 않도록 저장소별 책임을 분리합니다.
@@ -205,6 +231,8 @@ docker compose up --build                 # AI + Qdrant
 
 | 찾는 내용 | 문서 |
 | --- | --- |
+| 문서 전체 탐색 | [Documentation Index](docs/README.md) |
+| 아키텍처와 코드 위치 | [Architecture & Code Tour](docs/architecture.md) |
 | Server 연결과 인증 | [AI Runtime Handshake](docs/ai-runtime-handshake.md) |
 | PLAN·ANALYZE 계약 | [Analyses Contract](docs/analyses-contract.md) |
 | Renewal Agent 계약 | [Workflows Contract](docs/workflows-contract.md) |

docs/README.md

@@ -0,0 +1,55 @@
+# FOWOCO AI Documentation
+
+이 디렉터리는 현재 실행 계약, 운영 가이드, 구현 과정 기록을 보존합니다.
+처음 저장소를 보는 심사위원과 개발자는 아래 추천 순서부터 확인하면 됩니다.
+
+## 추천 읽기 순서
+
+1. [저장소 README](../README.md) — 프로젝트 목표와 전체 기능
+2. [Architecture & Code Tour](architecture.md) — 설계 선택과 실제 코드 위치
+3. [Analyses Contract](analyses-contract.md) — PLAN·ANALYZE 요청·응답
+4. [Workflows Contract](workflows-contract.md) — Renewal Agent 실행 계약
+5. [AI Runtime Handshake](ai-runtime-handshake.md) — Server 연결과 인증
+
+## 현재 계약
+
+아래 문서는 현재 Server·AI 연동의 기준입니다.
+
+| 범위 | 문서 |
+| --- | --- |
+| PLAN·ANALYZE | [analyses-contract.md](analyses-contract.md) |
+| Renewal 실행 | [workflows-contract.md](workflows-contract.md) |
+| Slot 재보충 | [slot-refill-contract.md](slot-refill-contract.md) |
+| Language Assistant JSON Schema | [contracts](contracts) |
+| 요청·응답 예시 | [`../examples/analyses`](../examples/analyses), [`../examples/workflows`](../examples/workflows) |
+
+## Provider·운영 가이드
+
+| 범위 | 문서 |
+| --- | --- |
+| Server–AI 인증과 연결 | [ai-runtime-handshake.md](ai-runtime-handshake.md) |
+| Language Assistant 설정·장애 처리 | [language-assistant-operations.md](language-assistant-operations.md) |
+| CLOVA OCR 계약 | [clova-ocr-integration.md](clova-ocr-integration.md) |
+| HWP·HWPX 변환 검증 | [document-conversion-poc.md](document-conversion-poc.md) |
+| Language 품질 기준 | [evaluations/language-assistant-baseline.md](evaluations/language-assistant-baseline.md) |
+
+## 모듈별 상세 문서
+
+| 모듈 | 문서 |
+| --- | --- |
+| HTTP API | [`../app/api/README.md`](../app/api/README.md) |
+| Renewal Agent | [`../app/agents/workflow_graph/README.md`](../app/agents/workflow_graph/README.md) |
+| Language Assistant | [`../app/agents/language/README.md`](../app/agents/language/README.md) |
+| 문서 처리 | [`../app/documents/README.md`](../app/documents/README.md) |
+| HWPX MCP | [`../hwp-editor/README.md`](../hwp-editor/README.md) |
+
+## 구현 과정 기록
+
+다음 디렉터리는 설계·작업·검증 과정을 재현하기 위한 기록입니다. 현재 API 계약을
+확인할 때는 위의 **현재 계약** 문서를 우선합니다.
+
+- [`language-assistant/engineering`](language-assistant/engineering) — Language Assistant 설계, 작업, 검증 Evidence
+- [`superpowers`](superpowers) — OCR·문서 자동화 설계와 구현 계획
+
+과거 기록은 삭제하지 않습니다. 다만 현재 동작과 충돌할 경우 실행 코드, 테스트,
+현재 계약 문서 순으로 판단합니다.

docs/architecture.md

@@ -0,0 +1,109 @@
+# Architecture & Code Tour
+
+FOWOCO AI는 모델이 업무 DB를 직접 조작하는 자율 실행기가 아니라, Server가 제공한
+검증된 Context 안에서 판단과 Tool 실행 결과를 반환하는 내부 Runtime입니다.
+
+## 전체 경계
+
+```mermaid
+flowchart LR
+    C["Client\nHR 입력·검토"] --> S["Server\n인증·tenant·업무 상태"]
+    S -->|"PLAN: 원문"| A["AI Runtime\nIntent·Workflow 판단"]
+    A -->|"requestedFieldKeys"| S
+    S -->|"ANALYZE: 허용된 Context"| A
+    A --> G["Renewal LangGraph"]
+    G --> O["OCR Tool"]
+    G --> L["Language Tool"]
+    G --> D["HWP/HWPX Tool"]
+    O --> G
+    L --> G
+    D --> G
+    G -->|"구조화 결과·검토 상태"| S
+    S -->|"HR 승인 후 반영"| C
+```
+
+AI가 소유하는 것은 Prompt, 모델 라우팅, Agent 분기, Tool 조합입니다. 사용자 권한,
+사업장 격리, Task 전이, 공식 파일, 감사로그는 Server가 소유합니다.
+
+## 실행 파이프라인
+
+### 1. PLAN — 업무와 필요한 Context 결정
+
+- 진입: [`app/api/routes/analyses.py`](../app/api/routes/analyses.py)
+- 조합: [`app/api/dependencies.py`](../app/api/dependencies.py)
+- 실행: [`app/agents/pipeline.py`](../app/agents/pipeline.py)
+- Intent: [`app/agents/intent`](../app/agents/intent)
+
+PLAN은 `detectedIntent`, canonical `workflowId`, `requestedFieldKeys`를 반환합니다.
+Worker·Company 값을 직접 조회하지 않습니다.
+
+### 2. ANALYZE — Server Context로 질문·Candidate 생성
+
+Server는 PLAN 결정을 저장하고 권한이 확인된 값만 보충합니다. ANALYZE는
+`plannedIntent`, `plannedWorkflowId`를 재사용하므로 Intent 모델을 다시 호출하지 않습니다.
+
+- 질문 판단: [`app/agents/ambiguity`](../app/agents/ambiguity)
+- Workflow Candidate: [`app/agents/workflow`](../app/agents/workflow)
+- 계약 Fixture: [`examples/analyses`](../examples/analyses)
+
+### 3. Renewal — 명시적 상태 기반 분기
+
+- 그래프: [`app/agents/workflow_graph/graph.py`](../app/agents/workflow_graph/graph.py)
+- 상태: [`app/agents/workflow_graph/state.py`](../app/agents/workflow_graph/state.py)
+- Supervisor: [`app/agents/workflow_graph/supervisor.py`](../app/agents/workflow_graph/supervisor.py)
+- Node 동작: [`app/agents/workflow_graph/nodes`](../app/agents/workflow_graph/nodes)
+
+```mermaid
+stateDiagram-v2
+    [*] --> LoadContext
+    LoadContext --> Supervisor
+    Supervisor --> AskHR: HR 입력 부족
+    Supervisor --> Guide: 근로자 서류 부족
+    Guide --> AskWorker
+    Supervisor --> OCR: 검토할 신분서류
+    OCR --> Generate
+    Supervisor --> Generate: 필수정보 충족
+    Supervisor --> OutOfScope: 지원 범위 아님
+    AskHR --> [*]
+    AskWorker --> [*]
+    Generate --> [*]
+    OutOfScope --> [*]
+```
+
+## Tool과 Agent 판단 구분
+
+| 구분 | 코드 | 특징 |
+| --- | --- | --- |
+| Intent Agent | [`app/agents/intent`](../app/agents/intent) | BERT·Guardrail·A.X 결과를 공통 계약으로 변환 |
+| Renewal Agent | [`app/agents/workflow_graph`](../app/agents/workflow_graph) | Slot·서류 상태를 보고 다음 분기 제안 |
+| OCR Tool | [`app/ocr`](../app/ocr) | CLOVA 응답을 허용된 문서 필드로 정규화 |
+| Language Tool | [`app/agents/language`](../app/agents/language) | 표준·쉬운 한국어와 대상 언어 초안 생성·검증 |
+| Document Tool | [`app/documents`](../app/documents) | 템플릿과 field map을 사용한 결정론적 생성·변환 |
+| HWPX MCP | [`hwp-editor`](../hwp-editor) | HWPX 구조 분석, 승인 편집, 무결성·시각 검증 |
+
+OCR·문서 Tool은 정해진 입력을 처리합니다. 어떤 Tool을 호출할지와 추가 정보가
+필요한지는 Agent가 제안합니다. 결과를 실제 업무에 반영할지는 Server와 HR이 결정합니다.
+
+## 실패 시 정책
+
+| 상황 | AI 응답 | Server 동작 |
+| --- | --- | --- |
+| Intent 모델 비활성 | Stub 또는 readiness 비가용 상태 | 데모·운영 설정을 구분 |
+| Worker Context 부족 | `CONTEXT_REQUIRED` 또는 `NEEDS_INFO` | 허용된 field만 조회하거나 HR 질문 |
+| 번역 실패·검토 필요 | `guideReviewRequired=true`, `workerRequestMessage=null` | 자동 발송 금지, HR 직접 검토 |
+| OCR 낮은 신뢰도 | 필드별 confidence와 검토 사유 | HR 승인 전 Worker 정보 미반영 |
+| 문서 Provider 실패 | 생성 실패 상태와 오류 코드 | 파일·Task 자동 완료 금지 |
+
+## 검증 코드
+
+| 검증 관점 | 위치 |
+| --- | --- |
+| API·인증 계약 | [`tests/api`](../tests/api) |
+| PLAN·ANALYZE Fixture | [`tests/contracts`](../tests/contracts) |
+| Intent·Workflow Agent | [`tests/agents`](../tests/agents) |
+| OCR 정규화·Provider 격리 | [`tests/ocr`](../tests/ocr) |
+| HWP·HWPX 생성·변환 | [`tests/documents`](../tests/documents) |
+| Qdrant·모델 선택 통합 | [`tests/integration`](../tests/integration) |
+
+기본 CI는 외부 Secret 없이 결정론적 테스트를 실행하고, Qdrant와 Windows OCR 계약을
+별도 Job으로 분리합니다. 실제 Provider 품질은 환경별 Smoke Test로 별도 확인합니다.