site11/CLAUDE.md

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

# 진행 상황 빠른 확인
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)

# 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)

# 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

# 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

# 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)

# 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