DocGen Project

DocGen — AI 기반 프로젝트 문서 자동 생성 플랫폼

효율성을 극대화한 프로젝트입니다.

1. 시스템 아키텍처 (System Architecture)

DocGen은 비즈니스 로직과 AI 처리 부하를 분산하기 위해 MSA(Microservice Architecture)를 채택했습니다. 

flowchart TB
  %%{init: {"flowchart": {"nodeSpacing": 25, "rankSpacing": 35}}}%%

  user["사용자"]

  subgraph DOCGEN["DOCGEN"]
    direction TB

    subgraph Browser["Browser"]
      direction TB
      spa["WebApp SPA
React + Vite"]
    end

    subgraph AcademyServer["학원 서버
(Docker Host)"]
      direction TB

      subgraph Compose["Docker Compose
(main)"]
        direction TB
        nginx["Nginx
Reverse Proxy · Static"]
        be1["Backend1 API
NestJS (Node.js)"]
        be2["Backend2 AI API
FastAPI (Python)"]
        pg["PostgreSQL"]
        mongo["MongoDB"]
        fs["File Storage
Docker Volume / Host FS"]
      end
    end
  end

  openai["OpenAI API"]
  gemini["Google Gemini API"]
  anthropic["Anthropic Claude API"]

  user -->|"HTTPS"| nginx
  nginx -->|"Static"| spa
  nginx -->|"Proxy /api"| be1
  nginx -->|"Proxy /ai"| be2

  spa -->|"REST API
(JWT)"| be1


  %% =========================
  %% DB / Storage (Hub)
  %% =========================
  dataHub["DB / Storage"]
  be1 --> dataHub
  be2 --> dataHub

  dataHub -->|"SQL
(TypeORM)"| pg
  dataHub -->|"Docs / Runs"| mongo
  dataHub -->|"Files"| fs


  %% =========================
  %% Service-to-service
  %% =========================
  be1 -->|"Generate docs
(HTTP)"| be2


  %% =========================
  %% LLM Providers (Hub)
  %% =========================
  llmHub["LLM Providers"]
  be2 -->|"LLM Call"| llmHub

  llmHub -->|"Call"| openai
  llmHub -->|"Call"| gemini
  llmHub -->|"Call"| anthropic


  %% =========================
  %% Styles
  %% =========================
  classDef person fill:#F3E8FF,stroke:#7C3AED,stroke-width:2px;
  classDef c_container fill:#E8F1FF,stroke:#2563EB,stroke-width:2px;
  classDef external fill:#FFF4E5,stroke:#F59E0B,stroke-width:2px;
  classDef datastore fill:#E9FBF0,stroke:#16A34A,stroke-width:2px;

  class user person;
  class spa,nginx,be1,be2,dataHub,llmHub c_container;
  class openai,gemini,anthropic external;
  class pg,mongo,fs datastore;

▲ React, NestJS, FastAPI 간의 데이터 흐름 및 DB 연결 구조

2. 주요 기능 및 화면 (UI/UX)

직관적인 대시보드와 스프레드시트 형태의 에디터를 통해 사용자 편의성을 높였습니다.

프로젝트 및 타임라인 관리

해시태그 기반 프로젝트 분류 및 진행 상황을 시각적으로 파악할 수 있는 타임라인 기능.

AI 문서 생성 및 엑셀 편집

요구사항(PRD), 기능명세(FSD) 자동 생성 후 Handsontable을 이용한 웹 엑셀 편집 지원.

3. AI 문서 생성 프로세스 (Logic Flow)

LangChain과 CrewAI를 활용한 멀티 에이전트(Multi-Agent) 시스템이 단계별로 문서를 구체화합니다. 

sequenceDiagram
    actor User
    participant API as FastAPI Server
    participant QGen as Question Agent
    participant ListGen as List Agent
    participant DetailGen as Detail Agent
    participant DB as MongoDB

    User->>API: 요구사항 입력
    API->>QGen: 핵심 질문 생성 요청
    QGen-->>API: 질문 리스트 반환
    API->>User: 질문 제시
    User->>API: 답변 제출
    
    rect rgb(240, 248, 255)
    Note right of API: 백그라운드 태스크 실행
    API->>ListGen: 요구사항 목록 생성 요청
    ListGen-->>API: 기능 목록(List)
    API->>DetailGen: 상세 스펙 작성 요청
    DetailGen-->>API: 상세 명세(Detail)
    end
    
    API->>DB: 최종 문서 저장
    API-->>User: 완료 알림 및 엑셀 다운로드

4. 데이터베이스 설계 (ERD)

정형 데이터는 PostgreSQL에, 비정형 문서 데이터는 MongoDB에 저장하는 Polyglot Persistence 전략을 사용했습니다.

▲ PostgreSQL 주요 테이블 관계도 (논리적 모델)

5. 기술 스택 (Tech Stack)

Frontend
React 19 TypeScript Vite Zustand Tailwind CSS Handsontable
Backend (Main)
NestJS Node.js TypeScript PostgreSQL TypeORM Swagger
AI Server
Python FastAPI MongoDB LangChain CrewAI OpenAI/Gemini

6. 트러블 슈팅

Jenkins + SonarQube + Docker 기반 CI/CD 구축 과정에서 겪었던 이슈를 증상 → 원인 → 해결 흐름으로 정리했습니다.

  • [1] Jenkins가 Docker 데몬에 연결되지 않음
    증상
    Cannot connect to the Docker daemon, permission denied 발생
    Jenkins 단계에서 docker build / docker ps 실행 실패
    원인
    Jenkins 실행 유저가 /var/run/docker.sock 접근 권한이 없거나
    Jenkins 컨테이너가 Docker 데몬 소켓을 마운트하지 않아 연결 경로가 끊김
    해결
    Jenkins 컨테이너에 /var/run/docker.sock 마운트(권장)
    빌드 노드/호스트에서 Jenkins 유저를 docker 그룹에 포함 후 재시작
  • [2] Dockerfile/소스가 누락되어 빌드 실패 (경로/컨텍스트 문제)
    증상
    Dockerfile not found, COPY failed: file not found in build context
    특정 파일이 이미지 빌드 컨텍스트에 포함되지 않아 단계에서 중단
    원인
    Jenkins가 체크아웃한 폴더와 실제 docker build 실행 위치가 달라
    빌드 컨텍스트가 잘못 잡힘(서브폴더/멀티모듈에서 특히 빈번)
    해결
    파이프라인에서 작업 디렉토리를 명확히 고정(dir(...) 개념)
    docker build -f path/to/Dockerfile . 처럼 Dockerfile 경로/컨텍스트를 명시
  • [3] SonarQube 컨테이너가 기동되지 않고 재시작 반복
    증상
    SonarQube가 계속 restart / healthcheck 실패
    로그에 Elasticsearch bootstrap check 또는 vm.max_map_count 관련 오류 노출
    원인
    Elasticsearch 요구 커널 설정(vm.max_map_count) 미충족 또는 메모리 부족
    (운영에서) 내장 DB 사용으로 안정성/성능 이슈 발생 가능
    해결
    호스트 커널 파라미터 설정(vm.max_map_count) 조정 후 재기동
    SonarQube 컨테이너 메모리 증설, 운영은 PostgreSQL 연동 구성 권장

▲ GoogleDrive를 통한 기획, 문서화, 협업 및 트러블 슈팅 관리

Project Info