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