refactor docs into technical specs

docs/technical/architecture-overview.md

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