v1.0.0

.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Markdown Lint
+name: CI-Dev
 
 on:
   pull_request:
@@ -7,13 +7,8 @@ on:
     branches: [dev]
 
 jobs:
-  markdownlint:
+  precommit:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-
-      - name: Run markdownlint
-        uses: DavidAnson/markdownlint-cli2-action@v16
-        with:
-          globs: |
-            **/*.md
+      - uses: pre-commit/action@v3.0.1

.pre-commit-config.yaml

@@ -1,4 +1,5 @@
 # .pre-commit-config.yaml
+exclude: scratch/
 
 repos:
   # 1. Standard Hooks (기본적인 파일 위생 및 문법 검사)

README.md

@@ -4,26 +4,57 @@
 
 ## 프로젝트 소개
 
-- **GTRPGM**은 룰북을 그래프 기반 지식 구조로 변환하고,
-  이를 바탕으로 시나리오를 구성하여 TRPG 세션을 진행하는
-  그래프 기반 게임 마스터 시스템입니다.
+> [시연 링크](http://35.216.98.244:8080/login)
+
+**GTRPGM**은 고정된 세계관과 룰 안에서
+시나리오를 그래프로 관리하고 상태를 추적하며,
+자연어 상호작용으로 일관성 있는 TRPG 플레이를 가능하게 하는
+AI 게임 마스터 시스템 입니다.
 
 ### 주요 기능
 
-- **Rule Graph (RG)**: 룰북을 그래프 기반 지식 베이스로 변환
-- **Scenario Graph (SG)**: RG를 기반으로 시나리오를 구성
-- **Graph-based Game Master (GGM)**: RG와 SG를 기반으로 TRPG 세션을 진행
+- **Rule Engine**: 자연어 입력을 룰북의 요소로 변환하고, 이를 기반으로 상태 업데이트를 계산
+- **Scenario Service**: 일관적인 세계관을 작성하고, 변화에 따른 시나리오 단계 변화 계산
+- **State Manager**: 플레이 세션별로 세계관의 변화 추적
+- **Game Master**: 위 서비스를 기반으로 일관성 있는 TRPG 세션을 진행
+
+### 🧩 서비스 구성 (Microservices)
+
+|       서비스명       | 역할 (Responsibility)                                              |
+| :------------------: | :----------------------------------------------------------------- |
+|    **GM Service**    | 게임의 메인 루프 실행, 턴 관리, 서사 생성, 에이전트 오케스트레이션 |
+| **Scenario Service** | 사용자 컨셉 기반 시나리오(Act/Sequence) 자동 생성 및 검증          |
+|   **Rule Engine**    | 게임 내 행동 판정(성공/실패), 주사위 굴림, 상태 변화 계산          |
+|  **State Manager**   | 게임 월드 상태(State) 저장 및 관리, 스냅샷 제공                    |
+|   **LLM Gateway**    | 모든 LLM 요청의 중앙 프록시, 모델 추상화 및 로깅                   |
+|    **BE-Router**     | 클라이언트와 내부 서비스 간의 API 게이트웨이 및 라우팅             |
+|       **Web**        | 사용자 인터페이스 (프론트엔드)                                     |
+
+### Technical Stack
+
+| 기술                 |          구분           | 사용 목적 및 상세                                                                  |
+| :------------------- | :---------------------: | :--------------------------------------------------------------------------------- |
+| **Python 3.11+**     |        Language         | 비동기 처리 및 풍부한 LLM 생태계(LangChain 등) 활용을 위한 주력 언어               |
+| **FastAPI**          |        Framework        | 고성능 비동기 API 서버 구축. Pydantic을 통한 자동 데이터 검증 및 Swagger 문서 제공 |
+| **Lang-chain**       |      LLM Framework      | llm 프롬프팅 및 에이전트 구성                                                      |
+| **Langgraph**        | Orchestration Framework | 상태기반 에이전트 오케스트레이션                                                   |
+| **Docker / Compose** |     Infrastructure      | 서비스 컨테이너화 및 로컬/운영 환경의 동일한 실행 환경(Environment) 보장           |
+| **Github Action**    |     Infrastructure      | CI/CD 자동화 워크플로우                                                            |
+| **PostgreSQL**       |        Database         | 관계형 데이터 저장. 서비스별 논리적 DB 분리를 통해 데이터 독립성 및 확장성 확보    |
+| **Redis**            |      Cache/Broker       | 세션 관리, API 게이트웨이의 라우팅 정보 저장 및 빈번한 데이터의 캐싱               |
+
+## 3. 설계 중점 사항 (Design Principles)
+
+1. **Decoupling**: 서비스 간 통신은 표준화된 REST API를 사용하며, 각 서비스의 내부 구현은 외부에서 알 수 없도록 캡슐화.
+2. **LLM Reliability**: LLM의 환각(Hallucination)이나 오류를 시스템적으로 보완하기 위해 검증용 에이전트(Reviewer)와 후처리 로직(Guardrails)을 기술적으로 배치.
 
 ## 프로젝트 레포지토리 설명
 
 - [**main**](./): 프로젝트 소개와 팀 협업·의사결정 과정을 함께 기록한 메인 레포지토리
-- [**core**](./): RG/SG/GGM 등 핵심 도메인 로직 구현
-- [**FE**](./): 프론트엔드 애플리케이션
-- [**BE**](./): 백엔드 API 및 세션 처리 로직
-- [**Ops**](./): 통합 테스트, 배포 설정, CI/CD 파이프라인
-
-### Main 레포지토리 구성
-
-## 📝 라이선스
-
-- 미정
+- [**rule-engine**](https://github.com/GTRPGM/rule-engine): 룰 엔진 서비스
+- [**GM**](https://github.com/GTRPGM/gm): 게임 마스터 서비스
+- [**state-manager**](https://github.com/GTRPGM/state-manager): 상태관리자 서비스
+- [**scenario-service**](https://github.com/GTRPGM/scenario-service): 시나리오 서비스
+- [**WEB**](https://github.com/GTRPGM/WEB): 프론트엔드 애플리케이션
+- [**BE**](https://github.com/GTRPGM/BE-router): 백엔드 API 및 세션 처리 로직 및 LLM 게이트웨이
+- [**infra**](https://github.com/GTRPGM/infra): 통합 테스트, DB 설정 및 배포

docs/plan.md

@@ -0,0 +1,116 @@
+# Plan of GTRPGM
+
+## 방향성
+
+- 룰 준수뿐 아니라 시나리오와 플레이 로그에 부합하는 플레이를 통해 플레이어 몰입 극대화
+- 고정된 룰과 세계관 내에서 반 고정된 시나리오를 자유롭게 탐색
+
+### 핵심 기능
+
+- 세계관/구조적으로 일관적인 시나리오 생성
+- 자연어로 생성된 시나리오를 분기 및 병합되는 그래프로 변환
+- 시나리오 그래프를 기반으로 플레이 상태를 시나리오 그래프에 추가해가며 플레이 진행
+- 자연어 발화로 기반으로 룰 선택
+- 선택된 룰을 기반으로 상태 업데이트 내용 산출
+- 업데이트 된 상태를 자연어로 변환하여 서술
+- 전체 플레이가 시나리오에 정합되게 플레이 진행 및 룰 판정 결과 조정
+
+## 아키텍쳐
+
+![GTRPGM Architecture](./GTRPGM.architexture.png)
+
+### 룰 엔진
+
+- 액션으로부터 인스턴스 및 규칙 추출
+- DB에서 룰 선택
+- 룰 + 인스턴스 기반 상태 변경 결과 산출
+- 상태 변경 결과를 GM에 전달
+- 시나리오 라이터에서 룰 조회를 위한 인터페이스 제공
+
+### 시나리오 라이터
+
+- 세계관 요약 및 입력값을 기반으로 시나리오 작성
+- 시나리오를 그래프 구조로 파싱
+
+### GM
+
+- 플레이어 입력 / GM 입력을 기반으로 룰 엔진 호출
+- 룰 엔진 결과를 시나리오 정합성에 맞게 수정
+- 상태 변경 적용 및 자연어로 결과 전달
+- 상태 요약
+
+### BE Router
+
+- 프런트 요청을 받아 MSA 호출
+- MSA 결과를 프런트로 반환
+
+### LLM Gateway
+
+- 공통 LLM 요청 및 응답 관리
+
+## MVP Scope
+
+### MVP (S0)
+
+- [ ] 룰 엔진
+  - [ ] 룰 구현을 위한 RDB 설계
+  - [ ] 자연어 발화를 기반으로 룰 선택
+  - [ ] 선택된 룰을 기반으로 상태 업데이트 내용 산출
+
+- [ ] 시나리오 라이터
+  - [ ] 룰 대이터 및 세계관 데이터를 기반으로 일관된 시나리오 생성
+  - [ ] 자연어로 생성된 시나리오를 그래프로 변환
+  - [ ] 시나리오 상태 전이 조건 정의
+
+- [ ] GM
+  - [ ] 플레이어 턴
+    - [ ] 주어진 시나리오와 상황에 대해 서술하고 플레이어의 행동을 요구
+    - [ ] 룰 엔진에 플레이어 행동 변환 요청
+  - [ ] GM 턴
+    - [ ] 플레이어 외의 모든 요소에 대해 업데이트
+    - [ ] 룰 엔진에 플레이어 외 대상들의 행동 변환 요청 (ex. 고블린의 공격 등)
+  - [ ] 공통
+    - [ ] 상태 업데이트가 시나리오에 부합하는지 판단 및 조정 (ex. 공격 수치를 줄이기)
+    - [ ] 상태 업데이트 적용
+    - [ ] 상태 업데이트 결과 산출
+
+- [ ] FE
+  - [ ] 선택지 ui 없이 채팅 기반 TRPG 진행
+  - [ ] 기본 채팅 요소 - 입력, 히스토리, 세션 관리
+  - [ ] 세계 상태 요약 - 시퀀스 내 캐릭터, 장비 등
+
+### S1
+
+- [ ] 품질 개선
+  - [ ] 멀티 에이전트
+  - [ ] 프롬프트 튜닝 및 엔지니어링
+  - [ ] 컨텍스트 관리 개선(캐싱 등)
+  - [ ] SLM 도입 검토
+  - [ ] 파이프라인 정리 및 최적화
+
+- [ ] FE
+  - [ ] 멀티 세션 및 유저 관리
+  - [ ] 로그인 ui
+
+- [ ] BE
+  - [ ] 멀티 유저 도입
+  - [ ] 로그인 및 세션 관리
+  - [ ] 옵저빌리티 확보 및 개선
+
+### S2
+
+- [ ] 지표 개선
+  - [ ] 베이스라인 측정
+  - [ ] 레이턴시 및 토큰 사용량 개선
+
+- [ ] 추가 기능
+  - [ ] 룰북 및 세계관 추가
+
+- [ ] BE
+  - [ ] 동시 접속 및 트래픽 테스트
+  - [ ] 배치 처리 및 요청
+  - [ ] 스케일 아웃 테스트
+
+- [ ] FE
+  - [ ] 디자인 개선
+  - [ ] 시나리오 편집 ui

docs/terms.md

@@ -0,0 +1,45 @@
+# 용어 합의
+
+## 컴포넌트 약어
+
+| 약어 | 지칭            |
+| ---- | --------------- |
+| FE   | 프런트 엔드     |
+| BE   | 백엔드          |
+| GM   | 게임 마스터     |
+| RUE  | 룰 엔진         |
+| SWR  | 시나리오 라이터 |
+
+## 시스템 내부
+
+### 공통
+
+| 용어     | 뜻                                             |
+| -------- | ---------------------------------------------- |
+| NPC      | 적을 포함한 플레이 불가 캐릭터, GM이 행동 결정 |
+| 플레이어 | 사용자                                         |
+| 시나리오 | 스토리마다 달라질 수 있는 요소                 |
+| 세계관   | 스토리들에 공통으로 적용되어야 하는 요소       |
+| 룰       | 세계관중 규칙에 해당하는 요소                  |
+
+### 플레이 세션
+
+> 고정된 시나리오 내에서 GM이 작동하는 전 과정
+
+| 용어        | 뜻                                                                   |
+| ----------- | -------------------------------------------------------------------- |
+| 플레이 세션 | 고정된 시나리오 상에서 플레이어의 진행 내역과 상태                   |
+| 룰 판정     | 자연어 행동에 대해 GM이 RUE에게 상태 업데이트 결과를 반환하라는 요구 |
+| 행동        | 상태 업데이트를 유발하는 플레이어와 NPC의 행동                       |
+| 상태        | 플레이 세션의 특정 지점을 재현하기 위한 변수 집합                    |
+
+### 시나리오 세션
+
+> Action → Sequence → Act → Scenario
+
+| 용어       | 뜻                                             |
+| ---------- | ---------------------------------------------- |
+| 액션(행동) | 상태 업데이트를 유발하는 플레이어와 NPC의 행동 |
+| 시퀀스     | 일정한 플레이 스타일을 유지하는 행동 묶음      |
+| 액트       | 시나리오 진행을 위한 시퀀스 묶음               |
+| 시나리오   | 전체 스토리 흐름을 만드는 액트 묶음            |