# 01. Technical Overview

## 솔루션 개요

AI 시험지 인식·손글씨 첨삭 SaaS는 시험지 원본을 SaaS에 저장하고, 사용자 PC 또는 내부 서버에서 실행되는 Local Agent가 OCR/VLM/LLM 후보를 생성하는 구조다. LLM은 최종 채점자가 아니며 풀이 인식 후보, 오류 가능성 후보, 첨삭 문구 후보만 생성한다.

핵심 원칙은 다음과 같다.

- 인식하지 못한 것은 추론하지 않는다.
- 추론한 것은 확정하지 않는다.
- 승인된 첨삭만 출력한다.

## 전체 아키텍처

```text
Browser UI
  |-- SaaS API: 프로젝트, 파일 메타데이터, 영역, 결과, 승인, 이력 저장
  |-- Local Agent direct call: health check, mock OCR/LLM/render/export

Flownco backend
  |-- JSON DEV_LOCAL store
  |-- AuditLog
  |-- ExportGuard
  |-- Admin data API

User PC Local Agent
  |-- OpenCV/OCR/Local LLM adapter
  |-- LLM Provider Router
  |-- external API blocked by default
  |-- deterministic handwriting SVG/PDF renderer
```

## SaaS 서버 역할

- 프로젝트와 업로드 문서 메타데이터 저장
- 업로드 페이지 수 제한 검증
- 문항/답안/첨삭 가능 영역 저장
- OCR/VLM 결과와 인식불가영역 저장
- 교사 전사, 풀이 추론 후보, 첨삭 후보 저장
- 승인/거절 이력 및 AuditLog 저장
- ExportGuard 실행 및 PDF 출력 이력 저장
- 관리자 조회 및 JSON/CSV export 제공

## Local Agent 역할

- 사용자 PC 또는 내부 서버에서 실행
- `/health`로 연결 상태 제공
- 스캔 전처리, OCR/VLM mock 또는 local endpoint 호출
- LLM Provider Router로 provider 프로파일과 허용/차단 상태 제공
- 인식불가영역 후보 생성
- 풀이 오류 가능성 후보 생성
- 첨삭 문구 후보 생성
- 승인 문구를 deterministic SVG로 렌더링
- 외부 API 호출은 기본 차단

## LLM Provider Router

SaaS Web은 사용자가 입력한 Local Agent `IP:Port`로 직접 연결한다. Flownco 서버는 사용자가 입력한 임의 IP로 proxy 요청하지 않는다. Local Agent 내부의 Provider Router가 모델 provider를 선택한다.

```text
SaaS Web
  -> 사용자가 입력한 Local Agent IP:Port
  -> Local Agent FastAPI :8787
  -> LLM Provider Router
       |- DeepSeek API: https://api.deepseek.com, deepseek-v4-pro / deepseek-v4-flash
       |- HyperCLOVA X Local vLLM: http://127.0.0.1:8001/v1, HyperCLOVAX-SEED-Think-14B
       |- HyperCLOVA X Vision Local vLLM: http://127.0.0.1:8002/v1, HyperCLOVAX-SEED-Vision-Instruct-3B
       |- Ollama / LM Studio / llama.cpp: http://127.0.0.1:11434/v1
```

MVP 기본 정책에서는 DeepSeek API를 포함한 외부 API provider가 비활성화된다. DeepSeek 계열 reasoning은 local DeepSeek-R1-Distill 모델을 우선 지원한다. 외부 API provider를 실제로 활성화하려면 별도 운영 승인, 개인정보·원본 이미지 전송 정책 검토, 환경변수 변경이 필요하다.

## LLM 단계별 역할

1. 스캔 전처리: LLM 없음
2. 풀이 영역 인식: OCR + local Vision model 후보
3. 인식불가영역 탐지: OCR confidence + Vision 교차검증 후보
4. 풀이 추론: local Think/DeepSeek-R1-Distill 후보
5. 첨삭 문구 생성: local Text model 후보
6. JSON 보정: 선택적 local small text model
7. 손글씨풍 출력: LLM 없음
8. 최종 승인: 교사

## 교사 승인 워크플로우

인식불가영역이 남아 있으면 풀이 추론과 PDF 출력으로 진행할 수 없다. DRAFT 또는 REVIEW_REQUIRED annotation이 남아 있으면 PDF 출력할 수 없다. 최종 PDF에는 APPROVED annotation만 포함한다.

## 관리자 데이터 수집 구조

모든 POST/PATCH/DELETE는 AuditLog를 남긴다. 관리자 페이지는 프로젝트, 문서, 페이지, 영역, 인식 결과, 인식불가영역, 교사 전사, 풀이 추론 후보, 첨삭 후보, 승인 이력, 출력 이력, Local Backend 설정, 연결 이력, 오류 로그를 조회한다.