safe-project/docs/architecture.md

TK 안전관리 플랫폼 - 아키텍처 가이드

기술 스택

분류	기술
프레임워크	Next.js 15 (App Router, TypeScript, Server Actions)
UI	Tailwind CSS + shadcn/ui + Lucide icons + recharts
ORM	Drizzle ORM
DB	PostgreSQL 16 (컨테이너 tk-safety-db)
AI 생성	맥미니 Ollama qwen3.5:35b-a3b
AI 임베딩	조립컴 Ollama bge-m3 (1024d)
벡터DB	Qdrant (컬렉션 safety-docs)
OCR	Apache Tika (port 9998)
인증	단일 사용자 (환경변수 비밀번호 + HMAC 쿠키 세션)

포트 매핑

서비스	호스트:컨테이너
tk-safety (Next.js)	3100:3000
tk-safety-db (PostgreSQL)	127.0.0.1:5433:5432

프로젝트 구조

tk-safety/
├── docker-compose.yml      # 서비스 정의
├── Dockerfile              # multi-stage 빌드 (standalone)
├── .env / .env.example     # 환경변수
├── drizzle.config.ts       # Drizzle ORM 설정
├── drizzle/migrations/     # DB 마이그레이션 (자동 생성)
├── uploads/                # 업로드 파일 (documents, photos)
├── docs/                   # 프로젝트 가이드 문서
└── src/
    ├── app/
    │   ├── layout.tsx              # 루트 레이아웃 (다크모드 초기화)
    │   ├── page.tsx                # 인증 리다이렉트
    │   ├── login/page.tsx          # 로그인 페이지
    │   ├── middleware.ts           # 인증 미들웨어
    │   ├── (authenticated)/        # 인증 필요 라우트 그룹
    │   │   ├── layout.tsx          # 사이드바 + 헤더
    │   │   ├── dashboard/          # 대시보드
    │   │   ├── risk-assessment/    # 위험성평가
    │   │   ├── rag/                # 안전 Q&A
    │   │   ├── checklists/         # 점검 체크리스트
    │   │   └── settings/           # 설정
    │   └── api/
    │       ├── auth/               # 로그인/로그아웃 API
    │       ├── ai/                 # AI 엔드포인트 (SSE 스트리밍)
    │       └── health/             # 서비스 헬스체크
    ├── actions/                    # Server Actions (CRUD)
    ├── components/
    │   ├── ui/                     # shadcn/ui 컴포넌트
    │   ├── layout/                 # 사이드바, 헤더, 모바일 내비
    │   ├── dashboard/              # 통계, 차트, 퀵액션
    │   ├── risk-assessment/        # 평가 폼, 매트릭스, AI 패널
    │   ├── rag/                    # 채팅, 문서 관리
    │   └── checklists/             # 템플릿, 점검, NCR
    ├── lib/
    │   ├── db/                     # schema.ts, index.ts
    │   ├── ai/                     # ollama, qdrant, tika, embeddings, prompts
    │   ├── auth.ts                 # 인증 유틸
    │   ├── constants.ts            # 상수 정의
    │   └── utils.ts                # shadcn 유틸
    ├── hooks/                      # use-streaming.ts (SSE)
    └── types/                      # 타입 정의

DB 스키마 (12개 테이블)

위험성평가

• risk_assessments — 평가 마스터 (제목, 상태, 버전)
• risk_assessment_hazards — 유해위험요인 (S×L=위험성)

RAG 문서

• rag_documents — 업로드 문서 (처리 상태 포함)
• rag_chunks — 문서 청크 (Qdrant pointId 매핑)
• rag_conversations — 대화 세션
• rag_messages — 메시지 (질문/답변 + 출처)

체크리스트

• checklist_templates — 점검 템플릿
• checklist_template_items — 템플릿 항목
• inspections — 점검 실행 기록
• inspection_results — 항목별 결과
• non_conformances — 부적합 사항 (NCR)

기타

• app_settings — 앱 설정 (key-value)

AI 연동 흐름

RAG Q&A

질문 → bge-m3 임베딩(조립컴) → Qdrant 검색(top-5) → 컨텍스트 + 질문 → qwen3.5 생성(맥미니) → SSE 스트리밍

AI 위험요인 추천

작업 설명 → bge-m3 임베딩 → Qdrant 검색(top-3) → 컨텍스트 + 프롬프트 → qwen3.5 JSON 생성 → 구조화 응답

문서 처리 파이프라인

파일 업로드 → Tika 텍스트 추출 → 1500자/200 overlap 청킹 → bge-m3 배치 임베딩(10개씩) → Qdrant 저장