portfolio-hub/docs/technical/project-structure-baseline.md

Project Structure Baseline

• Related REQ: N/A

목표

portfolio-hub 구현 및 유지보수 시 디렉토리 책임을 명확히 하여 API/CLI/도메인/저장소 변경의 영향 범위를 예측 가능하게 유지한다.

Target Baseline Structure

경로	책임	구현 메모
docs/SRS/	외부 계약, 승인 기준, REQ 상태 관리	requirement source of truth
docs/technical/	구현 상세 설계와 운영 메모	SRS를 재정의하지 않음
app/api/	HTTP 라우트, 요청/응답 경계	서비스 계층 호출 전담
app/cli/	Typer CLI 명령과 입출력	서비스 계층 재사용
app/services/	유스케이스 조합, 권한/검증 흐름	API/CLI 공통 오케스트레이션
app/domain/	포트폴리오 비즈니스 규칙	기술 의존성 최소화
app/repositories/	영속성 인터페이스와 구현체	DB feature flag 지원
app/schemas/	API 계약 스키마(Pydantic)	요청/응답 안정성
migrations/	Alembic 마이그레이션	스키마 변경 이력
tests/	API/도메인/CLI/계약 테스트	회귀 방지 게이트

Root-Level Exception Rules

• 루트에는 README.md, pyproject.toml, alembic.ini, .github/ 등 저장소 메타파일만 둔다.
• 실행 코드와 테스트 코드는 목적 디렉토리로 수렴시킨다.

Documentation Responsibilities

• README.md: 빠른 시작, 실행 방법, 운영 필수 변수 요약
• docs/SRS/: 왜(Why), 무엇(What), 수락 기준
• docs/technical/: 어떻게(How), 모듈 경계, 예시 흐름

Validation Notes

• 신규 모듈 추가 시 책임이 상기 경로 정의와 충돌하지 않는지 확인한다.
• API 계약 변경 시 app/schemas/와 docs/technical/api-contracts.md를 함께 동기화한다.
• 스키마 변경 시 migrations/versions/와 문서 업데이트를 같은 변경 단위에 포함한다.

Open Implementation Points

• Redis/Loki 실제 운영 경로가 코드에 전면 반영되면 app/core/ 또는 별도 infra 패키지 분리 여부를 확정한다.
• 태그 검색 기능(REQ-002) 구현 시 서비스/리포지토리 경계의 책임 분리를 추가 명세한다.