portfolio-hub/docs/technical/architecture-overview.md

Architecture Overview

• Related REQ: REQ-003

목표

portfolio-hub는 포트폴리오 상태 관리 기능을 API와 CLI에 동일하게 제공하고, 서비스/도메인/리포지토리 계층 분리를 통해 변경 비용을 낮춘다.

개요와 범위

런타임/구성요소 기준:

• Runtime: Python 3.11+
• API framework: FastAPI
• CLI framework: Typer
• DB driver: Psycopg v3
• Migration: Alembic

주요 목표:

• 포트폴리오 lifecycle 관리(create/update/delete/reset)
• 거래 및 잔고 영향 액션 기록(buy/sell/invest/transfer)
• API와 CLI에서 동일한 상태/ledger 조회 제공
• 공유 service/repository 계층을 통한 동작 일관성 유지

현재 범위:

• 인증된 포트폴리오 조회/변경 작업
• 관리자 기반 사용자 CRUD
• 권한 계층(read, trade-write, admin)
• feature flag 기반 PostgreSQL/Timescale 저장소
• DB bootstrap 및 migration 운영 명령

현재 비목표 / 제한:

• production 용도 메모리 fallback repository 미구현
• 외부 broker 주문 실행 미포함
• Redis/Loki 관측성 경로는 완전한 runtime wiring 미완료

상위 구성 요소

컴포넌트	책임
app/main.py	FastAPI 앱 생성, 라우터 등록, 설정 초기화
app/api/	인증/헬스/포트폴리오/전략셋/사용자 라우트
app/cli/	운영용 명령 인터페이스와 확인 프롬프트
app/services/	API/CLI 공통 유스케이스 수행
app/domain/	포트폴리오 거래 규칙, 밸런스 계산
app/repositories/	저장소 추상화 및 Postgres 구현
app/db/, migrations/	DB 초기화 및 스키마 버전 관리

엔트리포인트

HTTP 서비스:

• App factory: app.main:create_app
• ASGI app: app.main:app
• OpenAPI docs: /docs
• ReDoc: /redoc

CLI:

• Console script: portfoliohub
• Entry function: app.cli.main:main

기본 런타임 흐름

1. API 기반 거래 처리

1. 라우트에서 요청 바디와 권한을 검증한다.
2. 서비스 계층에서 도메인 규칙(수량/금액/상태)을 평가한다.
3. 리포지토리에서 포트폴리오/원장 데이터를 갱신한다.
4. 응답 스키마로 직렬화해 반환한다.

2. CLI 기반 동일 작업 처리

1. CLI 명령이 인자를 파싱하고 확인 프롬프트를 처리한다.
2. API와 동일한 서비스 메서드를 호출한다.
3. 결과를 터미널 친화 포맷으로 출력한다.

3. DB 활성화 경로

1. PORTFOLIOHUB_DB_ENABLED=true 확인
2. DB 연결 정보(TIMESCALEDB_*) 로딩
3. Postgres 리포지토리 선택
4. 필요 시 Alembic 마이그레이션 후 서비스 기동

설계 원칙

• Service Reuse First: API/CLI는 동일 service 계층을 재사용한다.
• Contract Stability: 외부 계약은 app/schemas/와 기술 문서에서 일관성을 유지한다.
• Persistence Isolation: 영속성 구현 세부사항은 repository 계층에 격리한다.
• Fail Fast Config: 필수 설정 누락은 조기 실패로 드러낸다.

테스트와 호환성 기준

테스트 기준:

• 테스트 프레임워크는 pytest를 사용한다.
• 주요 테스트 범위는 API, auth, CLI, domain service를 포함한다.
• 재귀 제외 경로는 temp, .git, .venv를 사용한다.

버전/호환성 기준:

• 현재 패키지 버전: 0.1.0
• API 버전 노출은 앱 버전 설정(app_version)을 따른다.
• 최소 Python 버전: 3.11

향후 확장 포인트

• Redis 기반 cache/session 통합
• Loki logging pipeline 통합
• 추가 broker 및 order-execution adapter
• 운영/admin 확장 엔드포인트

Open Implementation Points

• REQ-002 태그 검색 구현 시 조회 성능 요구를 만족하는 인덱스/쿼리 전략을 확정한다.
• 관측성(메트릭/로그)의 표준 이벤트 스키마를 별도 문서로 확장할지 결정한다.