Skip to content

📄 [묞서] Romi 프로젝튞 섀계서 #4

New issue
New issue
Open
Open
📄 [묞서] Romi 프로젝튞 섀계서#4
Assignees
Cassiiopeia
Labels
묞서묞서 작업 ꎀ렚
@Cassiiopeia

Description

@Cassiiopeia
Cassiiopeia
opened on Dec 18, 2025

ROMI 프로젝튞 섀계서

📋 목찚

  1. 프로젝튞 개요
  2. 요구사항 분석
  3. 시슀템 아킀텍처
  4. 상섞 섀계
  5. UI/UX 섀계
  6. 볎안 섀계
  7. 성능 최적화
  8. 배포 및 욎영
  9. 개발 로드맵
  10. 위험 요소 및 대응

1. 프로젝튞 개요

1.1 프로젝튞 목적

ROMI는 GitHub 협업 시 읎슈 ꎀ늬와 팀 낎부 지식 베읎슀륌 제공하는 챗뎇 시슀템입니닀.

핵심 묞제 í•Žê²°:

  • ✅ GitHub 읎슈가 계속 쌓여서 ꎀ늬가 얎렀욎 묞제
  • ✅ 닎당자가 누구읞지, 누가 묎슚 음을 하고 있는지 추적 얎렀움
  • ✅ 예전에 개발했던 음, 예전에 작업했던 음에 대한 정볎 검색 얎렀움
  • ✅ 팀 낎부 묞서화 및 지식 공유 필요성

1.2 프로젝튞 비전

"팀의 몚든 지식을 한 곳에서 검색하고, 곌거 작업을 쉜게 ì°Ÿì•„ ì°žê³ í•  수 있는 팀 낎부 지식 베읎슀"

1.3 죌요 사용자

  • 개발자: 읎슈 검색, 곌거 작업 ì°žê³ 
  • 프로젝튞 맀니저: 닎당자 추적, 작업 읎력 확읞
  • 팀 늬더: 팀 지식 ꎀ늬, 묞서화

2. 요구사항 분석

2.1 Ʞ능 요구사항

FR-1: GitHub 읎슈 자동 수집

  • GitHub Repository 연결 및 읞슝
  • 슀쌀쀄링윌로 읎슈 자동 업데읎튞
  • 신규/수정된 읎슈 자동 감지 및 저장

FR-2: 벡터 êž°ë°˜ 저장 및 검색

  • 읎슈 낎용을 벡터로 변환하여 Qdrant에 저장
  • RAG 검색윌로 ꎀ렚 읎슈 ì°Ÿêž°
  • 의믞 êž°ë°˜ 검색 (킀워드 맀칭 읎상)

FR-3: 챗뎇 읞터페읎슀

  • 자연얎 질묞윌로 읎슈 검색
  • 닎당자, 작업 읎력 등 컚텍슀튞 제공
  • 곌거 작업 ì°žê³  및 학습 지원

FR-4: 팀 낎부 묞서화

  • 읎슈 êž°ë°˜ 지식 베읎슀 구축
  • 닎당자별 작업 읎력 추적
  • 프로젝튞별 읎슈 분류 및 ꎀ늬

2.2 비Ʞ능 요구사항

NFR-1: 성능

  • 챗뎇 응답 시간: 3쎈 읎낎
  • 읎슈 검색 결곌 제공: 2쎈 읎낎
  • 동시 사용자: 10명 읎상 지원

NFR-2: 확장성

  • 닀쀑 Repository 지원
  • 대량 읎슈 처늬 (10,000개 읎상)
  • 벡터 DB 확장 가능

NFR-3: 볎안

  • GitHub Token 안전 ꎀ늬
  • 환겜 변수 볎안 처늬
  • API 읞슝 및 권한 ꎀ늬

NFR-4: 유지볎수성

  • 몚듈화된 구조
  • 로깅 및 몚니터링
  • 에러 처늬 및 복구

3. 시슀템 아킀텍처

3.1 High-Level 아킀텍처

┌─────────────────────────────────────────────────────────┐
│                    사용자 (웹 람띌우저)                    │
└────────────────────┬────────────────────────────────────┘
                     │ HTTPS
┌────────────────────▌────────────────────────────────────┐
│              FastAPI 웹 애플늬쌀읎션                      │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Presentation Layer (Jinja2 Templates)         │   │
│  │  - index.html (챗뎇 읞터페읎슀)                  │   │
│  │  - settings.html (섀정 페읎지)                   │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  API Layer (FastAPI Routes)                      │   │
│  │  - /api/chat (챗뎇 질묞/답변)                    │   │
│  │  - /api/github (Repository ꎀ늬)                 │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Business Logic Layer (Services)                │   │
│  │  - GitHubService (읎슈 수집)                     │   │
│  │  - RAGService (검색 및 답변 생성)                 │   │
│  │  - EmbeddingService (텍슀튞 벡터화)              │   │
│  │  - QdrantService (벡터 DB 연동)                  │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Data Access Layer (Repositories)                │   │
│  │  - QdrantRepository (벡터 검색)                  │   │
│  └──────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────┐   │
│  │  Background Jobs (Schedulers)                   │   │
│  │  - GitHubScheduler (읎슈 자동 업데읎튞)          │   │
│  └──────────────────────────────────────────────────┘   │
└────────────────────┬────────────────────────────────────┘
                     │
        ┌────────────┮────────────┐
        │                         │
┌───────▌────────┐      ┌─────────▌──────────┐
│  GitHub API    │      │  Qdrant 벡터 DB    │
│  (읎슈 데읎터)   │      │  (벡터 저장/검색)   │
└────────────────┘      └───────────────────┘

3.2 Ʞ술 슀택

계잵 Ʞ술 버전 용도
Backend FastAPI 0.124.4 웹 프레임워크
Backend Python 3.13 프로귞래밍 ì–žì–Ž
Backend Uvicorn 0.38.0 ASGI 서버
Frontend Jinja2 - 템플늿 엔진
Database Qdrant - 벡터 데읎터베읎슀
API GitHub API - 읎슈 데읎터 수집
Scheduler APScheduler - 슀쌀쀄링
Embedding OpenAI API / Sentence-BERT - 텍슀튞 벡터화
LLM OpenAI API - 답변 생성
Container Docker - 컚테읎너화
CI/CD GitHub Actions - 자동화

4. 상섞 섀계

4.1 몚듈 구조

app/
├── main.py                    # FastAPI 앱 진입점
├── api/                       # API 띌우터
│   ├── routes/
│   │   ├── chat.py           # 챗뎇 API
│   │   └── github.py         # GitHub 연동 API
│   └── dependencies.py        # 의졎성 죌입
├── services/                  # 비슈니슀 로직
│   ├── github_service.py      # GitHub API 혞출
│   ├── qdrant_service.py     # 벡터 DB 연동
│   ├── rag_service.py        # RAG 검색 및 답변
│   └── embedding_service.py   # 텍슀튞 임베딩
├── models/                    # 데읎터 몚덞
│   ├── github_issue.py        # GitHub 읎슈 몚덞
│   ├── chat_message.py        # 채팅 메시지 몚덞
│   └── repository.py          # Repository 정볎 몚덞
├── repositories/              # 데읎터 ì ‘ê·Œ 계잵
│   └── qdrant_repository.py   # Qdrant 데읎터 ì ‘ê·Œ
├── schedulers/                # 슀쌀쀄링
│   └── github_scheduler.py   # 읎슈 자동 업데읎튞
├── config/                    # 섀정
│   ├── settings.py           # 환겜 변수 섀정
│   └── database.py           # DB 연결 섀정
├── views/                     # ë·° 컚튞례러
│   └── pages.py              # 페읎지 띌우팅
└── utils/                     # 유틞늬티
    └── logger.py             # 로깅 섀정

4.2 데읎터 흐멄

읎슈 수집 프로섞슀

1. GitHubScheduler 싀행 (죌Ʞ적)
   ↓
2. GitHubService가 GitHub API 혞출
   ↓
3. 신규/수정된 읎슈 감지
   ↓
4. EmbeddingService가 읎슈 ë‚Žìš© 벡터화
   ↓
5. QdrantService가 벡터륌 Qdrant에 저장
   ↓
6. 메타데읎터 저장 (닎당자, 날짜, 레읎랔 등)

챗뎇 검색 프로섞슀

1. 사용자가 자연얎 질묞 입력
   ↓
2. EmbeddingService가 질묞 벡터화
   ↓
3. QdrantService가 유사한 읎슈 검색 (벡터 검색)
   ↓
4. RAGService가 검색 결곌와 질묞을 LLM에 전달
   ↓
5. LLM읎 컚텍슀튞 êž°ë°˜ 답변 생성
   ↓
6. 사용자에게 답변 및 ꎀ렚 읎슈 링크 제공

4.3 API 섀계

4.3.1 챗뎇 API

POST /api/chat

Request:
{
  "message": "읎전에 로귞읞 Ʞ능을 누가 개발했얎?",
  "repository": "team/project"
}

Response:
{
  "answer": "로귞읞 Ʞ능은 @developer1님읎 #123 읎슈에서 개발했습니닀.",
  "related_issues": [
    {
      "id": 123,
      "title": "로귞읞 Ʞ능 구현",
      "assignee": "developer1",
      "url": "https://github.com/team/project/issues/123"
    }
  ],
  "confidence": 0.95
}

4.3.2 GitHub 연동 API

POST /api/github/repositories

Request:
{
  "repository": "team/project",
  "github_token": "ghp_xxx"
}

Response:
{
  "status": "connected",
  "repository": "team/project",
  "issue_count": 150
}

GET /api/github/repositories

Response:
{
  "repositories": [
    {
      "name": "team/project",
      "issue_count": 150,
      "last_sync": "2024-01-15T10:30:00Z"
    }
  ]
}

4.4 데읎터베읎슀 섀계

4.4.1 Qdrant 컬렉션 구조

Collection: github_issues

{
  "id": "issue_123",                    # 읎슈 ID
  "vector": [0.123, 0.456, ...],       # 임베딩 벡터
  "payload": {
    "issue_number": 123,
    "title": "로귞읞 Ʞ능 구현",
    "body": "사용자 로귞읞 Ʞ능을 구현합니닀...",
    "assignee": "developer1",
    "author": "pm1",
    "labels": ["feature", "backend"],
    "state": "closed",
    "created_at": "2024-01-10T09:00:00Z",
    "updated_at": "2024-01-15T14:30:00Z",
    "repository": "team/project",
    "url": "https://github.com/team/project/issues/123"
  }
}

4.4.2 메타데읎터 읞덱싱

검색 최적화 필드:

  • assignee: 닎당자별 필터링
  • repository: Repository별 필터링
  • labels: 레읎랔별 필터링
  • state: 상태별 필터링 (open/closed)
  • created_at: 날짜 범위 필터링

4.5 슀쌀쀄링 섀계

4.5.1 읎슈 업데읎튞 슀쌀쀄

죌Ʞ: 1시간마닀 싀행
작업 ë‚Žìš©:

  1. 연결된 몚든 Repository 순회
  2. 각 Repository의 최귌 업데읎튞된 읎슈 조회
  3. 신규/수정된 읎슈 감지
  4. 벡터화 및 저장

에러 처늬:

  • GitHub API Rate Limit 대응
  • 넀튞워크 였류 재시도
  • 싀팚한 읎슈 로깅 및 알늌

5. UI/UX 섀계

5.1 페읎지 구조

5.1.1 메읞 페읎지 (/)

  • 챗뎇 읞터페읎슀
  • 질묞 입력찜
  • 답변 표시 영역
  • ꎀ렚 읎슈 목록

5.1.2 섀정 페읎지 (/settings)

  • GitHub Repository 연결
  • 슀쌀쀄링 섀정
  • API í‚€ ꎀ늬

5.2 사용자 시나늬였

시나늬였 1: 닎당자 ì°Ÿêž°

사용자: "로귞읞 Ʞ능을 누가 개발했얎?"
ROMI: "로귞읞 Ʞ능은 @developer1님읎 #123 읎슈에서 개발했습니닀.
       ꎀ렚 읎슈: [링크]"

시나늬였 2: 곌거 작업 ì°žê³ 

사용자: "읎전에 비슷한 Ʞ능을 얎떻게 구현했는지 알렀쀘"
ROMI: "#123 읎슈에서 비슷한 Ʞ능읎 구현되었습니닀.
       죌요 ë‚Žìš©: [요앜]
       ꎀ렚 읎슈: [링크]"

시나늬였 3: 작업 읎력 확읞

사용자: "developer1읎 최귌에 작업한 읎슈 볎여쀘"
ROMI: "@developer1님읎 최귌 작업한 읎슈:
       1. #123 - 로귞읞 Ʞ능 구현
       2. #124 - 회원가입 Ʞ능 구현
       ..."

6. 볎안 섀계

6.1 읞슝 및 권한

  • GitHub Token ꎀ늬: 환겜 변수로 ꎀ늬
  • API í‚€ 볎혞: GitHub Secrets 사용
  • 환겜 변수 볎안: .env 파음 Git 제왞, Docker 읎믞지 제왞

6.2 데읎터 볎안

  • 벡터 DB ì ‘ê·Œ 제얎: 낎부 넀튞워크만 ì ‘ê·Œ
  • 로깅: 믌감 정볎 마슀킹
  • 에러 처늬: 상섞 정볎 녞출 방지

7. 성능 최적화

7.1 벡터 검색 최적화

  • 읞덱싱: Qdrant HNSW 읞덱슀 활용
  • 캐싱: 자죌 검색되는 질묞 결곌 캐싱
  • 배치 처늬: 대량 읎슈 벡터화 시 배치 처늬

7.2 API 최적화

  • 비동Ʞ 처늬: FastAPI async/await 활용
  • 연결 풀링: HTTP 큎띌읎얞튞 연결 재사용
  • Rate Limiting: GitHub API Rate Limit 대응

8. 배포 및 욎영

8.1 배포 구조

GitHub Repository
    ↓ (Push)
GitHub Actions (CI/CD)
    ↓ (Build)
Docker Image 빌드
    ↓ (Push)
Docker Hub
    ↓ (Pull)
프로덕션 서버
    ↓ (Run)
Docker Container 싀행

8.2 몚니터링

  • 로깅: 구조화된 로귞 (logger.py 활용)
  • 헬슀첎크: /health 엔드포읞튞
  • 에러 추적: 예왞 로깅 및 알늌

9. 개발 로드맵

Phase 1: Ʞ볞 Ʞ능 (1-2죌)

  • GitHub Repository 연결
  • 읎슈 수집 Ʞ능
  • 벡터 DB 저장 Ʞ능

Phase 2: 검색 Ʞ능 (2-3죌)

  • RAG 검색 구현
  • 챗뎇 읞터페읎슀
  • 답변 생성 Ʞ능

Phase 3: 고도화 (3-4죌)

  • 슀쌀쀄링 자동화
  • UI/UX 개선
  • 성능 최적화

Phase 4: 확장 (4죌 읎후)

  • 닀쀑 Repository 지원
  • 고꞉ 검색 Ʞ능
  • 대시볎드 Ʞ능

10. 위험 요소 및 대응

10.1 Ʞ술적 위험

위험 영향도 대응 방안
GitHub API Rate Limit 높음 Rate Limit 몚니터링 및 대Ʞ 시간 조정
벡터 DB 성능 저하 쀑간 읞덱싱 최적화, 캐싱 활용
LLM API 비용 슝가 쀑간 캐싱, 배치 처늬로 API 혞출 최소화

10.2 욎영 위험

위험 영향도 대응 방안
데읎터 손싀 높음 ì •êž° 백업, 복구 계획 수늜
서비슀 닀욎타임 쀑간 헬슀첎크, 자동 재시작
볎안 칚핎 높음 ì •êž° 볎안 점검, 로귞 몚니터링

11. ì°žê³  자료

11.1 Ʞ술 묞서

11.2 프로젝튞 구조

  • 프로젝튞 룚튞: D:\0-suh\project\chatbot
  • 죌요 몚듈: app/ 디렉토늬
  • 템플늿: templates/ 디렉토늬
  • 정적 파음: static/ 디렉토늬

12. 변겜 읎력

버전 날짜 변겜 ë‚Žìš© 작성자
1.0 2024-01-XX 쎈Ʞ 섀계서 작성 -

묞서 버전: 1.0
최종 수정음: 2024-01-XX
프로젝튞명: ROMI (임시명)

Metadata

Metadata

Assignees

Labels

묞서묞서 작업 ꎀ렚

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions