Initial commit - cleaned repository

2025-09-28 20:41:57 +09:00
commit e3c28f796a
188 changed files with 28102 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,275 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Principles
+**IMPORTANT**: 
+1. 모든 개발은 Docker 환경에서만 진행
+2. Docker 빌드는 백그라운드로 실행하고 완료까지 대기
+3. 로컬 환경 설정 금지 (venv, npm install 등)
+
+## File Naming Convention
+**IMPORTANT**: 모든 문서 파일은 대문자.md 형식으로 생성
+- 예: README.md, CHANGELOG.md, TODO.md, ARCHITECTURE.md
+
+## Context Recovery Guide
+**IMPORTANT**: 새 세션 시작 시 반드시 확인할 파일들:
+1. `docs/PROGRESS.md` - 현재 진행 상황과 다음 단계
+2. `docs/PLAN.md` - 전체 구현 계획
+3. `docker ps` - 실행 중인 서비스 확인
+
+## Quick Status Check
+```bash
+# 진행 상황 빠른 확인
+cat docs/PROGRESS.md | grep "Next Action"
+```
+
+## System Architecture
+
+### Architecture Pattern: Microservices with Central Console
+
+**Core Concept**: Console acts as the orchestrator and dashboard, while individual microservices handle domain-specific logic.
+
+### Architecture Approaches
+
+#### 1. API Gateway Pattern (Recommended)
+Console serves as an API Gateway that:
+- Routes requests to appropriate microservices
+- Handles authentication/authorization centrally
+- Aggregates responses from multiple services
+- Provides service discovery and health monitoring
+
+#### 2. Service Mesh Pattern
+- Each service communicates directly via service mesh (Istio/Linkerd)
+- Console focuses on monitoring and management
+- Better for complex inter-service communication
+
+#### 3. Event-Driven Architecture
+- Services communicate via message broker (RabbitMQ/Kafka)
+- Console subscribes to events for real-time monitoring
+- Loose coupling between services
+
+### Technology Stack
+- **Backend**: FastAPI (Python 3.11) + Motor (MongoDB async driver)
+- **Frontend**: React 18 + Vite + TypeScript + Material-UI v7
+- **Database**: MongoDB 7.0
+- **Cache**: Redis 7
+- **Reverse Proxy**: Nginx
+- **Container**: Docker & Docker Compose
+- **Version Control**: git
+- **API Documentation**: OpenAPI/Swagger
+- **Service Communication**: REST + gRPC (for internal services)
+
+### Service Configuration
+- **Nginx**: Port 80 (reverse proxy)
+- **Console Backend**: Port 8000 (API Gateway)
+- **Console Frontend**: Port 3000
+- **Services**: 
+  - Images: 8001-8002
+  - OAuth: 8003-8004
+  - Applications: 8005-8006
+  - Users: 8007-8008
+  - Data: 8009-8010
+  - Statistics: 8011-8012
+- **MongoDB**: Port 27017 (internal)
+- **Redis**: Port 6379 (internal)
+
+## Microservices Implementation Strategy
+
+### Console as API Gateway (Recommended Approach)
+
+#### Responsibilities
+**Console Backend**:
+- Service discovery and routing
+- Authentication & authorization (JWT/OAuth2)
+- Request/response transformation
+- Rate limiting & throttling
+- Circuit breaking for fault tolerance
+- Centralized logging & monitoring
+- API composition for complex operations
+
+**Individual Microservices**:
+- Domain-specific business logic
+- Own database/collection management
+- Event publishing for async operations
+- Health endpoints for monitoring
+- OpenAPI documentation
+
+### Service Communication Patterns
+
+#### 1. Synchronous Communication (REST)
+```python
+# Console backend routing example
+@app.get("/api/users/{user_id}")
+async def get_user(user_id: str):
+    # Route to users service
+    response = await http_client.get(f"http://users-service:8007/users/{user_id}")
+    return response.json()
+```
+
+#### 2. Asynchronous Communication (Event-driven)
+```python
+# Service publishes event
+await redis_client.publish("user.created", user_data)
+
+# Console subscribes to events
+async def handle_user_created(data):
+    # Update dashboard metrics
+    await update_statistics(data)
+```
+
+#### 3. Service Registry Pattern
+```yaml
+# services-registry.yaml
+services:
+  users:
+    backend: "http://users-backend:8007"
+    frontend: "http://users-frontend:8008"
+    health: "/health"
+  oauth:
+    backend: "http://oauth-backend:8003"
+    frontend: "http://oauth-frontend:8004"
+    health: "/health"
+```
+
+### Development Workflow
+
+#### Commands
+```bash
+# Start all services
+docker-compose up -d
+
+# Start specific service
+docker-compose up -d console users
+
+# View logs
+docker-compose logs -f [service-name]
+
+# Rebuild service
+docker-compose build [service-name]
+docker-compose up -d [service-name]
+
+# Run tests
+docker-compose exec [service-name] pytest
+
+# Database migrations
+docker-compose exec [service-name] alembic upgrade head
+```
+
+#### Service Development Guidelines
+1. Each service should be independently deployable
+2. Services share nothing except API contracts
+3. Use correlation IDs for distributed tracing
+4. Implement health checks and readiness probes
+5. Version APIs appropriately (e.g., /api/v1/)
+
+## Project Structure
+
+```
+site11/
+├── docker-compose.yml
+├── nginx/
+│   └── nginx.conf
+├── console/
+│   ├── backend/
+│   │   ├── Dockerfile
+│   │   └── requirements.txt
+│   └── frontend/
+│       ├── Dockerfile
+│       ├── package.json
+│       ├── vite.config.ts
+│       ├── tsconfig.json
+│       └── src/
+│           ├── App.tsx
+│           ├── main.tsx
+│           ├── layouts/
+│           │   └── AdminLayout.tsx
+│           └── pages/
+│               ├── Login.tsx
+│               └── Register.tsx
+├── services/
+│   ├── images/
+│   │   ├── backend/
+│   │   └── frontend/
+│   ├── oatuh/
+│   │   ├── backend/
+│   │   └── frontend/
+│   ├── applications/
+│   │   ├── backend/
+│   │   └── frontend/
+│   ├── users/
+│   │   ├── backend/
+│   │   └── frontend/
+│   ├── data/
+│   │   ├── backend/
+│   │   └── frontend/
+│   └── statistics/
+│       ├── backend/
+│       └── frontend/
+├── docs/
+│   └── PLAN.md  
+└── CLAUDE.md
+```
+
+## Service-Specific Architecture
+
+### Console Service
+- **Purpose**: Central orchestrator and dashboard
+- **Key Features**:
+  - Service health monitoring dashboard
+  - Unified authentication portal
+  - API Gateway for all services
+  - Real-time metrics aggregation
+  - Service configuration management
+
+### Microservice Template
+Each service follows this structure:
+```
+service-name/
+├── backend/
+│   ├── Dockerfile
+│   ├── requirements.txt
+│   ├── app/
+│   │   ├── main.py          # FastAPI app
+│   │   ├── models.py        # Pydantic models
+│   │   ├── routes.py        # API endpoints
+│   │   ├── database.py      # MongoDB connection
+│   │   └── services.py      # Business logic
+│   └── tests/
+└── frontend/
+    ├── Dockerfile
+    ├── package.json
+    └── src/
+        ├── api/             # Service API client
+        ├── components/      # React components
+        └── hooks/           # Custom hooks
+```
+
+## Inter-Service Communication
+
+### API Gateway Routes (Console)
+```python
+# Console backend routing configuration
+SERVICES = {
+    "users": {"url": "http://users-backend:8007", "prefix": "/api/users"},
+    "oauth": {"url": "http://oauth-backend:8003", "prefix": "/api/auth"},
+    "images": {"url": "http://images-backend:8001", "prefix": "/api/images"},
+    "applications": {"url": "http://apps-backend:8005", "prefix": "/api/apps"},
+    "data": {"url": "http://data-backend:8009", "prefix": "/api/data"},
+    "statistics": {"url": "http://stats-backend:8011", "prefix": "/api/stats"}
+}
+```
+
+### Service Discovery
+Services register themselves with Console on startup and send periodic heartbeats.
+
+## Database Strategy
+- **Shared MongoDB instance** with separate databases per service
+- **Redis** for caching and pub/sub messaging
+- Each service owns its data and exposes it via APIs
+
+## Security Considerations
+- JWT tokens issued by OAuth service
+- Console validates tokens and forwards to services
+- Internal service communication uses service tokens
+- Rate limiting at API Gateway level