🏗️ timiroom-backend (Spring Boot 메인 백엔드, port 8080)
src/main/java/com/timiroom/
TimiroomBackendApplication.java
└─ @SpringBootApplication 진입점. Spring Boot 애플리케이션 실행
config/
└─ SecurityConfig.java
· CSRF 비활성화, CORS 허용 (localhost:3000)
· OAuth2 로그인 설정 (Google, GitHub)
· 세션 기반 인증 (SessionCreationPolicy.IF_REQUIRED)
· /auth/**, /oauth2/**, /login/** 공개 허용 / 나머지 인증 필요
· 401 응답 시 JSON 에러 반환 (리다이렉트 아님)
· 로그아웃: POST /auth/logout → 세션 무효화 + JSESSIONID 삭제
domain/member/
├─ Member.java # 회원 엔티티 — id, email, name, provider, providerId, role
├─ MemberController.java # GET /auth/me (세션에서 memberId 읽어 회원 정보 반환)
├─ MemberRepository.java # findByProviderAndProviderId — OAuth 로그인 시 기존 회원 조회
├─ Provider.java # OAuth 공급자 enum (GOOGLE, GITHUB)
├─ Role.java # 권한 enum (USER, ADMIN)
├─ dto/MemberLoginRequest.java # 이메일/비밀번호 로그인 요청 DTO
├─ dto/MemberRegisterRequest.java # 회원가입 요청 DTO
└─ service/MemberService.java # 회원 조회·수정 비즈니스 로직
domain/notification/
├─ Notification.java # 알림 엔티티 — memberId, type, referenceType, referenceId, content, isRead
├─ NotificationController.java # GET /api/v1/notifications (내 알림 목록), DELETE /{id}
├─ NotificationRepository.java # findByMemberId, findByMemberIdAndIsReadFalse
├─ NotificationReferenceType.java # 알림 대상 타입 enum (PROJECT, PIPELINE, REQUIREMENT 등)
├─ NotificationService.java # 알림 생성·조회·읽음 처리 로직
└─ NotificationType.java # 알림 종류 enum (PIPELINE_COMPLETE, PROJECT_INVITE 등)
domain/oauth/
├─ OAuth2MemberService.java # OAuth2UserService 구현 — Google/GitHub 사용자 정보로
│ # Member 신규 생성 또는 기존 회원 조회·반환
└─ OAuth2SuccessHandler.java # OAuth 로그인 성공 핸들러
# · HttpSession에 memberId 저장
# · <http://localhost:3000/auth/callback> 으로 리다이렉트
domain/pipeline/
├─ PipelineArtifact.java # AI 결과물 아티팩트 엔티티 — executionId, artifactType, content(JSON 텍스트)
├─ PipelineArtifactRepository.java # findByExecutionId
├─ PipelineController.java # POST /api/v1/pipeline/start/{requirementId} — 파이프라인 시작
│ # GET /api/v1/pipeline/progress/{pipelineId} — SSE 진행 프록시
│ # GET /api/v1/pipeline/executions/{id}/artifacts — 결과 조회
├─ PipelineExecution.java # 파이프라인 실행 기록 엔티티 — requirementId, pipelineId(UUID), status
├─ PipelineExecutionRepository.java # findByPipelineId
└─ PipelineService.java # RagPipelineClient로 rag-pipeline(8081) 호출
# · 파이프라인 시작 → executionId, pipelineId 반환
# · SSE 스트림 중계 (rag-pipeline → 프론트)
domain/project/
├─ Project.java # 프로젝트 엔티티 — name, description, status, color, teamId, consistencyScore
├─ ProjectController.java # GET /api/v1/projects — 내 프로젝트 목록
│ # POST /api/v1/projects — 프로젝트 생성
│ # GET /api/v1/projects/{id} — 단일 조회
│ # PATCH /api/v1/projects/{id} — 수정
│ # DELETE /api/v1/projects/{id} — 삭제
├─ ProjectMember.java # 프로젝트-멤버 N:M 연결 엔티티
├─ ProjectMemberRepository.java # findByProjectId, findByMemberId
├─ ProjectRepository.java # findByTeamId
├─ ProjectRole.java # 프로젝트 내 역할 enum (OWNER, MEMBER)
├─ ProjectService.java # 프로젝트 CRUD + 멤버 권한 검증
└─ ProjectStatus.java # 상태 enum — PLANNING / IN_PROGRESS / COMPLETED
# (프론트 projectApi.js에서 draft / active / completed 로 변환)
domain/requirement/
├─ Requirement.java # 요구사항 엔티티 — projectId, title, content, status
├─ RequirementController.java # POST /api/v1/requirements — 요구사항 생성
│ # GET /api/v1/requirements/{id} — 단일 조회
├─ RequirementRepository.java # findByProjectId
├─ RequirementService.java # 요구사항 생성·조회 로직
└─ RequirementStatus.java # 상태 enum (DRAFT, ACTIVE, COMPLETED)
domain/team/
├─ Team.java # 팀 엔티티 — teamName, description, ownerId
├─ TeamController.java # GET /api/v1/teams — 내 팀 목록
│ # POST /api/v1/teams — 팀 생성
├─ TeamMember.java # 팀-멤버 N:M 연결 엔티티
├─ TeamMemberRepository.java # findByTeamId, findByMemberId
├─ TeamRepository.java # findByOwnerId
├─ TeamRole.java # 팀 내 역할 enum (OWNER, MEMBER)
└─ TeamService.java # 팀 생성·조회·멤버 초대 로직
global/
└─ BaseEntity.java # JPA @MappedSuperclass — createdAt, updatedAt 자동 관리 (@PrePersist, @PreUpdate)
infra/ragpipeline/
└─ RagPipelineClient.java # WebClient 기반 rag-pipeline(8081) 클라이언트
# · generate() — POST /api/v1/orchestration/generate (multipart)
# FormData + 파일 전송, 응답에서 pipelineId(UUID) 추출 반환
# · getProgressFlux() — GET /api/v1/orchestration/progress/{id}
# SSE 스트림을 Flux<ServerSentEvent<String>>으로 중계
설정 파일
src/main/resources/
├── application.yml # 기본 설정 — DB(PostgreSQL), Redis, Neo4j, OAuth2 클라이언트 ID/Secret, port 8080
├── application-local.yml # 로컬 환경 — Kafka listener.auto-startup: false (로컬에서 Kafka 없이 기동 가능)
└── application-prod.yml # 프로덕션 환경 설정
📦 rag-pipeline (Spring Boot AI 파이프라인, port 8081)
src/main/java/com/rag/pipeline/
RagPipelineApplication.java # 스프링부트 진입점
common/agent/
└─ AgentController.java # 공통 에이전트 API 진입점 기반 클래스
common/config/
├─ AiModelConfig.java # Spring AI 모델 설정 — ChatClient Bean 등록 (Anthropic Claude)
├─ AsyncConfig.java # @EnableAsync + ThreadPoolTaskExecutor 설정 (에이전트 병렬 실행용)
├─ CorsConfig.java # CORS 허용 — localhost:3000, localhost:8080
├─ JacksonConfig.java # ObjectMapper 커스텀 — JSON 직렬화/역직렬화 설정
└─ RestClientConfig.java # Spring RestClient Bean 등록
common/dto/
└─ DocumentChunk.java # RAG 검색 결과 단위 — content, source, score, embedding
common/exception/
├─ ErrorCode.java # 에러 코드 enum — PIPELINE_FAILED, VALIDATION_ERROR 등
├─ ErrorResponse.java # 에러 응답 포맷 DTO — code, message, timestamp
└─ GlobalExceptionHandler.java # @RestControllerAdvice — 전역 예외를 ErrorResponse로 변환
common/logging/
└─ MdcLoggingFilter.java # MDC에 traceId, pipelineId 삽입 — 로그 추적용 필터
common/response/
└─ ApiResponse.java # 공통 응답 래퍼 — { success, code, data }
common/util/
└─ InMemoryMultipartFile.java # byte[] → MultipartFile 변환 유틸 (파싱된 PDF 재전송 시 사용)
phase1/
├─ RagController.java # GET /api/v1/rag/search — 하이브리드 검색 API
│ # POST /api/v1/rag/ingest — 문서 수집 API
├─ RagPipelineService.java # RAG 전체 흐름 조율 — 청킹 → 임베딩 → 저장 → 검색
└─ DocumentIngestionService.java # 문서 파싱·청킹·임베딩 후 PostgreSQL(pgvector)에 저장
phase1/chunking/
└─ SemanticChunkingService.java # 텍스트를 의미 단위로 분리 — 문장 경계 + 슬라이딩 윈도우
phase1/embedding/
└─ EmbeddingService.java # Spring AI EmbeddingModel 호출 → float[] 벡터 반환 (3072차원)
phase1/form/
├─ FormData.java # 프로젝트 생성 위자드 입력 전체 — 서비스명, 목표, 플랫폼, 기능 목록 등
├─ FormToQueryService.java # FormData → RAG 검색 쿼리 문자열 변환
├─ CommonFeature.java # 공통 기능 선택 항목 DTO
├─ CustomFeature.java # 사용자 직접 입력 기능 DTO
├─ FeatureDefinition.java # 기능 정의 (이름, 설명, MoSCoW 우선순위)
├─ MoSCoW.java # 우선순위 enum — Must / Should / Could / Won't
├─ PlatformType.java # 플랫폼 enum (WEB, MOBILE, DESKTOP 등)
├─ ProblemDefinition.java # 해결할 문제 정의 DTO
└─ TargetUser.java # 타겟 사용자 정의 DTO
phase1/parsing/
└─ PDFParsingService.java # Apache PDFBox로 PDF 텍스트 추출 → DocumentChunk 목록 반환
phase1/recommendation/
├─ RecommendationController.java # POST /api/v1/recommendation/features — 기능 추천
│ # POST /api/v1/recommendation/personas — 페르소나 추천
│ # POST /api/v1/recommendation/tech-stack — 기술 스택 추천
├─ FeatureRecommendationService.java # 입력 기반 AI 기능 목록 추천 (Claude 호출)
├─ FeatureRecommendationRequest.java # 기능 추천 요청 DTO
├─ FeatureRecommendationResponse.java # 기능 추천 응답 DTO
├─ PersonaRecommendationService.java # 타겟 사용자 페르소나 추천 (Claude 호출)
├─ PersonaRecommendationRequest.java # 페르소나 추천 요청 DTO
├─ PersonaRecommendationResponse.java # 페르소나 추천 응답 DTO
├─ TechStackRecommendationService.java # 기술 스택 추천 (Claude 호출)
├─ TechStackRequest.java # 기술 스택 추천 요청 DTO
├─ TechStackResponse.java # 기술 스택 추천 응답 DTO
├─ RecommendedFeature.java # 추천 기능 DTO — name, description, priority
└─ RecommendedPersona.java # 추천 페르소나 DTO — name, age, goals, painPoints
phase1/reranker/
└─ RerankerService.java # RAG 검색 결과 재순위화 — Cross-Encoder 또는 LLM 기반 relevance scoring
phase1/search/
├─ HybridSearchService.java # 하이브리드 검색 — pgvector 코사인 유사도(벡터) + PostgreSQL FTS(키워드) 혼합
└─ QueryExpansionService.java # 검색 쿼리 확장 — LLM으로 동의어·관련 키워드 추가 생성
phase1/session/
└─ SessionVectorStore.java # 파이프라인 세션별 임시 벡터 스토어 (in-memory, 세션 종료 시 제거)
phase2/
└─ OrchestrationController.java # POST /api/v1/orchestration/generate — 파이프라인 시작, pipelineId 반환
# GET /api/v1/orchestration/progress/{pipelineId} — SSE 진행 스트림
phase2/agent/
├─ PmAgent.java # PM 에이전트 — FormData 분석, 프로젝트 목표·범위·우선순위 정리
├─ PrdAgent.java # PRD 에이전트 — 기획 내용을 PRD 문서(JSON) 생성
│ # 출력: projectOverview, goals, userPersonas, coreFeatures, techStack 등
├─ SearchAgent.java # 검색 에이전트 — RAG로 유사 사례 검색, 컨텍스트 수집
├─ ApiAgent.java # API 명세 에이전트 — REST API 엔드포인트 목록 JSON 생성
│ # 출력: { endpoints: [...], authentication: "..." }
├─ DbaAgent.java # DB 스키마 에이전트 — ERD 기반 테이블/관계 JSON 생성
│ # 출력: { tables: [...], relationships: [...] }
└─ QaAgent.java # QA 에이전트 — 생성된 PRD/API/DB 간 정합성 검증, 이슈 리포트
phase2/dto/
├─ GenerateRequest.java # 파이프라인 시작 요청 DTO — query, formData, files
└─ GenerateResponse.java # 파이프라인 완료 응답 DTO
# · from(PipelineState) — projectId/projectName null (단독 호출 시)
# · from(PipelineState, projectId, projectName) — 값 포함 버전
# 필드: pipelineId, featureList, prdDocument, dbSchema, apiSpec, marketResearch
phase2/graph/
└─ OrchestrationGraph.java # 에이전트 실행 그래프 — LangGraph4j 스타일
# SearchAgent → PmAgent → (PrdAgent || ApiAgent || DbaAgent) 병렬 → QaAgent
phase2/sse/
└─ PipelineProgressService.java # SSE 이벤트 관리 — pipelineId별 SseEmitter 보관
# · sendProgress() — "progress" 이벤트 전송
# · complete() — "complete" 이벤트 + GenerateResponse 전송
# · error() — "error" 이벤트 전송
phase2/state/
└─ PipelineState.java # 파이프라인 공유 상태 객체 — 에이전트 간 데이터 전달
# pipelineId, query, formData, ragContext,
# featureList, prdDocument, dbSchema, apiSpec, marketResearch
phase3/retry/
└─ RetryService.java # 에이전트 실행 재시도 로직 — 최대 3회, 지수 백오프
phase3/validation/
├─ GenerationResult.java # 생성 결과 모델 — content, isValid, errorMessage
├─ SchemaValidator.java # JSON 스키마 검증 — 에이전트 출력이 기대 구조인지 확인
└─ ValidationService.java # PRD·API·DB 결과 교차 검증 — 불일치 항목 리포트
phase4/kafka/
├─ KafkaProducerService.java # 파이프라인 완료 시 Kafka 토픽에 결과 이벤트 발행
├─ KafkaConsumerService.java # Kafka 이벤트 소비 → PostgreSQL에 결과 영구 저장
└─ PipelineResultEvent.java # Kafka 메시지 DTO — pipelineId, projectId, PRD/API/DB JSON
설정 파일
src/main/resources/
├── application.yml # 기본 설정 — PostgreSQL(pgvector), Redis, Kafka, Spring AI, port 8081
├── application-local.yml # 로컬 환경 설정
└── application-prod.yml # 프로덕션 환경 설정
🎨 timiroom-frontend (Next.js, port 3000)
src/ 전체 구조
app/
├─ layout.jsx # 루트 레이아웃 — AuthProvider, 전역 폰트/스타일 적용
├─ page.jsx # 랜딩 페이지 — Navbar, Hero, Features, HowItWorks 등 섹션 조립
├─ globals.css # 전역 CSS — 리셋, 폰트 임포트, CSS 변수
├─ auth/callback/page.jsx # OAuth 콜백 처리 — 백엔드 리다이렉트 착지점
│ # login() 호출 → /auth/me → user 저장 → /dashboard 이동
└─ dashboard/page.jsx # 대시보드 메인 페이지 — 프로젝트 선택, 위자드, 패널 라우팅
components/auth/
└─ AuthModal.jsx # 소셜 로그인 모달 — Google/GitHub OAuth 버튼
# 버튼 클릭 → redirectToOAuth(provider) → Spring Boot OAuth2 엔드포인트로 이동
components/landing/
├─ Navbar.jsx # 내비게이션 바 — 로고, 메뉴, 로그인 버튼 (AuthModal 열기)
├─ Hero.jsx # 히어로 섹션 — 메인 카피, CTA 버튼
├─ Features.jsx # 기능 소개 섹션 — 주요 기능 카드 목록
├─ CoreCapabilities.jsx # 핵심 역량 섹션 — AI 파이프라인 능력 상세 설명
├─ HowItWorks.jsx # 사용 방법 섹션 — 단계별 플로우 설명
├─ Metrics.jsx # 수치·지표 섹션 — 카운터 애니메이션 (useCounter 훅 사용)
├─ TechStack.jsx # 기술 스택 섹션 — 사용 기술 아이콘/로고
├─ TrustSection.jsx # 신뢰도 섹션 — 로고, 수치 등
├─ CTACards.jsx # CTA 카드 섹션
├─ FooterCTA.jsx # 푸터 위 CTA 배너
├─ Footer.jsx # 푸터 — 링크, 카피라이트
├─ ScrollProgress.jsx # 상단 스크롤 진행률 바 (useScrollProgress 훅)
└─ index.js # 배럴 익스포트 — landing 컴포넌트 일괄 export
components/dashboard/
├─ DashboardLayout.jsx # 대시보드 전체 레이아웃 — ActivityBar + AppSidebar + 메인 패널 영역
├─ AppSidebar.jsx # 우측 앱 사이드바 — 프로젝트 목록 + 메뉴 항목
├─ ActivityBar.jsx # 좌측 아이콘 바 — 패널 전환 버튼 (PRD, ERD, API, Features 등)
├─ AiChatSidebar.jsx # AI 채팅 사이드바 — agentApi.js로 Claude와 대화, 프로젝트 컨텍스트 전달
├─ CreateProjectWizard.jsx # 프로젝트 생성 위자드 (다단계)
│ # · Step1: 서비스명/설명 입력
│ # · Step2: 기능 선택 (AI 추천 포함)
│ # · Step3: 파일 업로드, 기술스택/페르소나 추천
│ # · ProgressScreen: SSE로 파이프라인 진행 상황 실시간 표시
│ # · 완료 시 onComplete({ ...result, projectId, projectName }) 호출
├─ ProjectsListPage.jsx # 프로젝트 목록 뷰 — 프로젝트 카드, 검색, 필터
├─ PipelineView.jsx # 파이프라인 진행 시각화 — 에이전트별 상태 표시
├─ KnowledgeGraph.jsx # 지식 그래프 시각화 — PRD·API·DB 간 연결 관계 그래프
├─ AgentPanel.jsx # AI 에이전트 현황 패널 — 에이전트별 실행 상태·결과 표시
├─ OverviewPanel.jsx # 프로젝트 개요 패널 — 기본 정보, 정합성 스코어, 진행률
├─ PrdPanel.jsx # PRD 문서 패널 — prdDocument JSON → HTML 렌더링
│ # 섹션: 개요, 목표, 페르소나, 핵심 기능, MVP 범위, 기술 스택, 일정 등
├─ FeaturesPanel.jsx # 기능 목록 패널 — featureList를 카드 형태로 표시
├─ DocPanel.jsx # 문서 패널 — 기타 문서 뷰어
├─ ApiSpecPanel.jsx # API 명세 패널 — apiSpec JSON → Swagger-like UI 렌더링
│ # buildTagsFromApiSpec으로 endpoints 파싱, 제목은 "{프로젝트명} API"
├─ ErdPanel.jsx # ERD 패널 — dbSchema JSON → 테이블/관계 시각화
├─ ContextPanel.jsx # 컨텍스트 패널 — RAG 검색 결과·참고 문서 표시
└─ index.js # 배럴 익스포트
components/ui/
├─ Button.jsx # 공통 버튼 컴포넌트 — variant(primary/secondary/ghost), size
├─ SectionHeader.jsx # 섹션 헤더 — 제목 + 부제목
└─ index.js # 배럴 익스포트
context/
└─ AuthContext.jsx # 인증 전역 컨텍스트
# · 앱 시작 시 /auth/me 호출 → user 상태 복원
# · login(), logout(), openAuthModal() 제공
# · isLoading, isLoggedIn, user 상태 전파
hooks/
├─ useCounter.js # 숫자 카운터 애니메이션 훅 (랜딩 Metrics 섹션용)
├─ useMockProgress.js # 목업 진행률 상태 훅 (파이프라인 로딩 UI 테스트용)
├─ useScrollAnim.js # Intersection Observer 기반 스크롤 진입 애니메이션 훅
├─ useScrollProgress.js # 페이지 스크롤 진행률(0~1) 계산 훅
└─ index.js # 배럴 익스포트
lib/
├─ agentApi.js # AI 에이전트 채팅 API
│ # · sendMessage() — POST /api/agent/chat (일반 응답)
│ # · sendMessageStream() — POST /api/agent/chat/stream (SSE 스트리밍)
│ # · saveAgentConfig() / loadAgentConfig() — LLM 설정 localStorage 저장
│ # ※ credentials: "include" 세션 기반 인증
├─ projectApi.js # 프로젝트 CRUD API
│ # · fetchProjects(), fetchProject(id), createProject(), updateProject(), deleteProject()
│ # · normalizeProject() — 백엔드 응답 → 프론트 Project 객체 변환
│ # · normalizeStatus() — PLANNING→draft, IN_PROGRESS→active, COMPLETED→completed
├─ pipelineApi.js # 파이프라인 연동 API (백엔드 8080 경유)
│ # · createRequirement() — POST /api/v1/requirements
│ # · startPipeline() — POST /api/v1/pipeline/start/{requirementId} (파일 multipart)
│ # · subscribePipelineProgress() — SSE 구독 (progress / complete / error 이벤트)
│ # · getArtifacts() — GET /api/v1/pipeline/executions/{id}/artifacts
├─ teamApi.js # 팀 API
│ # · getMyTeams() — GET /api/v1/teams
│ # · createTeam() — POST /api/v1/teams
│ # · getOrCreateDefaultTeam() — 팀이 없으면 "내 팀" 자동 생성 후 반환
├─ recommendationApi.js # AI 추천 API (rag-pipeline 8081 직접 호출)
│ # · recommendFeatures(), recommendPersonas(), recommendTechStack()
├─ authConfig.js # 인증 설정 및 공통 유틸
│ # · API_BASE_URL (8080), RAG_PIPELINE_URL (8081), APP_URL
│ # · OAUTH_ENDPOINTS — Google/GitHub OAuth2 진입 URL
│ # · redirectToOAuth(provider) — OAuth 로그인 페이지로 이동
│ # · apiFetch() — credentials: "include", 401 시 "/" 리다이렉트
│ # (단, 이미 "/"이면 리다이렉트 생략 — 무한루프 방지)
├─ projectData.js # 프로젝트 더미 데이터 / 목 데이터 유틸 (개발용)
└─ smoothScroll.js # 앵커 링크 부드러운 스크롤 유틸
styles/
├─ landing.css # 랜딩 페이지 전용 스타일 — 섹션별 레이아웃, 애니메이션
└─ theme.css # 글로벌 CSS 변수 — 색상 팔레트, 폰트, 간격
🔄 Phase별 파이프라인 흐름
| Phase |
역할 |
주요 클래스 |
| Phase 1 |
RAG 검색 & 임베딩 — 문서 청킹·벡터 저장·하이브리드 검색 |
RagPipelineService, HybridSearchService, EmbeddingService, SemanticChunkingService |
| Phase 2 |
AI 에이전트 오케스트레이션 — 병렬 에이전트 실행 + SSE 진행 전송 |
OrchestrationGraph, PmAgent, PrdAgent, ApiAgent, DbaAgent, QaAgent, PipelineProgressService |
| Phase 3 |
결과 검증 & 재시도 — JSON 스키마 검증, 에이전트 간 교차 검증 |
ValidationService, RetryService, SchemaValidator |
| Phase 4 |
Kafka 이벤트 & DB 영구 저장 — 결과물 비동기 저장 |
KafkaProducerService, KafkaConsumerService, PipelineResultEvent |
🐛 버그 수정 기록 (2026-05-20)