# 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

## Deployment Guide

### News API Deployment
**IMPORTANT**: News API는 Kubernetes에 배포되며 Docker 이미지 버전 관리가 필요합니다.

상세 가이드: `services/news-api/DEPLOYMENT.md` 참조

#### Quick Deploy
```bash
# 1. 버전 설정
export VERSION=v1.1.0

# 2. 빌드 및 푸시 (버전 태그 + latest)
cd services/news-api
docker build -t yakenator/news-api:${VERSION} -t yakenator/news-api:latest -f backend/Dockerfile backend
docker push yakenator/news-api:${VERSION}
docker push yakenator/news-api:latest

# 3. Kubernetes 재시작
kubectl -n site11-news rollout restart deployment news-api-deployment
kubectl -n site11-news rollout status deployment news-api-deployment
```

#### Version Management
- **Major (v2.0.0)**: Breaking changes, API 스펙 변경
- **Minor (v1.1.0)**: 새 기능 추가, 하위 호환성 유지
- **Patch (v1.0.1)**: 버그 수정, 작은 개선

#### Rollback
```bash
# 이전 버전으로 롤백
kubectl -n site11-news rollout undo deployment news-api-deployment

# 특정 버전으로 롤백
kubectl -n site11-news set image deployment/news-api-deployment \
  news-api=yakenator/news-api:v1.0.0
```