auto-stock/docs/PROJECT_STRUCTURE.md

Auto Stock Trading System 프로젝트 구조

📁 디렉토리 구조

auto-stock/
├── backend/                          # FastAPI 백엔드
│   ├── app/
│   │   ├── api/
│   │   │   ├── __init__.py          # API 라우터 통합
│   │   │   └── endpoints/
│   │   │       ├── trading_rules.py # 트레이딩 규칙 API
│   │   │       ├── trades.py        # 거래 이력 API
│   │   │       ├── portfolio.py     # 포트폴리오 API
│   │   │       ├── market_data.py   # 시장 데이터 API
│   │   │       └── mcp.py           # MCP 연동 API
│   │   ├── core/
│   │   │   ├── config.py            # 설정 관리
│   │   │   └── database.py          # 데이터베이스 연결
│   │   ├── models/
│   │   │   └── models.py            # SQLAlchemy 모델
│   │   ├── services/
│   │   │   ├── websocket_manager.py # WebSocket 관리
│   │   │   └── korea_investment_api.py # 한국투자증권 API
│   │   └── main.py                  # FastAPI 앱 진입점
│   ├── Dockerfile
│   └── requirements.txt
│
├── mcp-server/                       # MCP 서버 (Claude AI)
│   ├── main.py                       # MCP 서버 진입점
│   ├── config.py                     # 설정
│   ├── claude_client.py              # Claude API 클라이언트
│   ├── mcp_tools.py                  # MCP 도구 레지스트리
│   ├── Dockerfile
│   └── requirements.txt
│
├── frontend/                         # React 프론트엔드
│   ├── src/
│   │   ├── components/
│   │   │   └── Layout.tsx           # 레이아웃 컴포넌트
│   │   ├── pages/
│   │   │   ├── Dashboard.tsx        # 대시보드
│   │   │   ├── TradingRules.tsx     # 트레이딩 규칙
│   │   │   ├── TradeHistory.tsx     # 거래 이력
│   │   │   └── MCPStatus.tsx        # MCP 상태
│   │   ├── hooks/
│   │   │   └── useWebSocket.ts      # WebSocket 훅
│   │   ├── lib/
│   │   │   └── api.ts               # API 클라이언트
│   │   ├── App.tsx                  # 앱 컴포넌트
│   │   ├── main.tsx                 # 진입점
│   │   ├── config.ts                # 설정
│   │   └── index.css                # 스타일
│   ├── public/
│   ├── index.html
│   ├── package.json
│   ├── vite.config.ts
│   ├── tailwind.config.js
│   ├── tsconfig.json
│   ├── nginx.conf
│   └── Dockerfile
│
├── docker/                           # Docker 설정
│   └── init-db.sql                  # DB 초기화 스크립트
│
├── scripts/                          # 유틸리티 스크립트
│   ├── deploy.sh                    # 프로덕션 배포
│   ├── dev.sh                       # 개발 모드
│   ├── stop.sh                      # 시스템 중지
│   ├── restart.sh                   # 재시작
│   ├── logs.sh                      # 로그 확인
│   └── backup.sh                    # DB 백업
│
├── .github/
│   └── workflows/
│       └── ci-cd.yml                # CI/CD 파이프라인
│
├── docker-compose.yml               # 프로덕션 Docker Compose
├── docker-compose.dev.yml           # 개발용 Docker Compose
├── .env.example                     # 환경 변수 예시
├── .gitignore
├── Makefile                         # Make 명령어
├── ecosystem.config.js              # PM2 설정
├── README.md                        # 프로젝트 소개
├── INSTALLATION.md                  # 설치 가이드
├── USER_GUIDE.md                    # 사용자 가이드
└── API_DOCS.md                      # API 문서

🎯 주요 기능

1. 대시보드

• 실시간 포트폴리오 현황
• 총 자산 및 수익률
• 보유 종목 상세

2. 전략 룰 설정

• 자동 매매 규칙 생성/수정/삭제
• 조건 및 액션 설정
• 규칙 우선순위 관리

3. 매매 로그

• 전체 거래 내역
• 실행 상태 모니터링
• 거래 통계

4. MCP 상태 모니터

• MCP 서버 연결 상태
• Claude AI 도구 목록
• 실시간 로그

🔧 기술 스택

Backend

• FastAPI: 비동기 REST API
• SQLAlchemy: ORM
• PostgreSQL: 데이터베이스
• Redis: 캐싱
• RabbitMQ: 메시지 큐
• WebSocket: 실시간 통신

MCP Server

• FastAPI: MCP 프로토콜 서버
• Anthropic Claude: AI 분석
• Pandas/TA: 기술적 지표 계산

Frontend

• React 18: UI 프레임워크
• TypeScript: 타입 안정성
• Vite: 빌드 도구
• TailwindCSS: 스타일링
• React Query: 데이터 페칭
• Recharts: 차트

Infrastructure

• Docker: 컨테이너화
• Docker Compose: 오케스트레이션
• Nginx: 웹 서버
• GitHub Actions: CI/CD

🚀 빠른 시작

1. 환경 설정

cp .env.example .env
# .env 파일 편집하여 API 키 설정

2. Docker로 시작

./scripts/deploy.sh

3. 접속

• Frontend: http://localhost:3000
• Backend: http://localhost:8000
• MCP Server: http://localhost:8001

📊 시스템 아키텍처

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Frontend  │────▶│   Backend    │────▶│ MCP Server  │
│   (React)   │     │  (FastAPI)   │     │  (Claude)   │
└─────────────┘     └──────────────┘     └─────────────┘
                           │                     │
                           ▼                     ▼
                    ┌──────────────┐     ┌─────────────┐
                    │  PostgreSQL  │     │  Claude AI  │
                    │    Redis     │     └─────────────┘
                    │  RabbitMQ    │
                    └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ 한국투자증권  │
                    │     API      │
                    └──────────────┘

🔐 보안

• API 키는 환경 변수로 관리
• JWT 토큰 기반 인증
• CORS 설정
• HTTPS 지원 (프로덕션)

📝 개발 가이드

Backend 개발

cd backend
pip install -r requirements.txt
uvicorn app.main:app --reload

MCP Server 개발

cd mcp-server
pip install -r requirements.txt
uvicorn main:app --reload --port 8001

Frontend 개발

cd frontend
npm install
npm run dev

🧪 테스트

# Backend 테스트
make test-backend

# Frontend 테스트
make test-frontend

📦 배포

Docker Compose

make deploy

PM2 (Node.js Process Manager)

pm2 start ecosystem.config.js

🛠️ 유용한 명령어

make help          # 도움말
make dev           # 개발 모드
make deploy        # 배포
make stop          # 중지
make restart       # 재시작
make logs          # 로그
make backup        # DB 백업
make clean         # 정리

📚 문서

• README.md - 프로젝트 소개
• INSTALLATION.md - 설치 가이드
• USER_GUIDE.md - 사용자 가이드
• API_DOCS.md - API 문서

⚠️ 주의사항

• 실제 거래 전 충분한 테스트 필요
• API 키 보안 관리
• 손실 위험 인지
• 규칙 신중하게 설정

📄 라이센스

MIT License

🤝 기여

Pull Request와 Issue는 언제나 환영합니다!