Develop

.github/pull_request_template.md

@@ -0,0 +1,67 @@
+## 한눈에 보기
+
+| 구분 | 내용 |
+|---|---|
+| 문제 |  |
+| 확인된 원인 |  |
+| 해결 방법 |  |
+| 사용자·개발자 영향 |  |
+
+<!-- PR 전체를 읽지 않아도 변경 이유와 결론을 이해할 수 있게 한 문장씩 작성합니다. -->
+
+## 확인 과정
+
+| 단계 | 확인한 내용 | 판단 근거 |
+|---:|---|---|
+| 1. 재현 |  |  |
+| 2. 원인 확인 |  |  |
+| 3. 해결안 선택 |  |  |
+
+<!-- 추측이 아니라 로그, 쿼리, 화면 동작, 테스트 실패처럼 직접 확인한 근거를 작성합니다. -->
+
+## 구현 내용
+
+| 영역 | 변경 내용 | 변경 이유 |
+|---|---|---|
+|  |  |  |
+
+<!-- API 응답, 이벤트, 데이터 형식처럼 유지한 동작이 있으면 함께 작성합니다. -->
+
+## 검증 조건
+
+| 항목 | 조건 |
+|---|---|
+| 테스트 대상 |  |
+| 데이터·환경 |  |
+| 실행 횟수·부하 |  |
+| 통과 기준 |  |
+
+<!-- 별도 측정이 필요 없는 PR은 불필요한 행을 삭제합니다. -->
+
+## 검증 결과
+
+| 확인 항목 | 변경 전 | 변경 후 | 판정 |
+|---|---:|---:|---|
+|  |  |  |  |
+
+| 지표 | 변경 전 | 변경 후 | 변화 |
+|---|---:|---:|---:|
+| p95 |  |  |  |
+| p99 |  |  |  |
+| 오류율 |  |  |  |
+| 병목 지표 |  |  |  |
+
+<!-- 기능 PR은 첫 표에 성공·실패 케이스를 작성합니다. 성능 PR은 두 표를 모두 사용합니다. 표의 기본 지표는 예시이며 구현사항에 따라 쿼리 수, 처리량, 자원 사용량, 성공 케이스 등 필요한 지표를 추가하거나 교체합니다. 결과가 나온 이유도 2~3문장으로 설명합니다. -->
+
+## 영향 범위와 후속 작업
+
+- 영향받는 기능:
+- 이번 PR에서 제외한 범위:
+- 다음 작업:
+
+## 체크리스트
+
+- [ ] 문제를 재현하고 원인을 확인했습니다.
+- [ ] 변경에 직접 관련된 테스트를 통과했습니다.
+- [ ] 기존 API·이벤트·화면 동작의 유지 여부를 확인했습니다.
+- [ ] 실행하지 못한 검증이나 남은 위험을 작성했습니다.

.gitignore

@@ -0,0 +1,2 @@
+.DS_Store
+apps/backend/target/

AGENTS.md

@@ -0,0 +1,65 @@
+# AGENTS.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

apps/backend/.gitignore

@@ -1,4 +1,5 @@
 uploads/*
+.env
 
 # Eclipse JDT / LSP 생성 파일
 .classpath

apps/backend/DEPLOY.md

@@ -117,6 +117,13 @@ tail -f logs/app.log
    REDIS_HOST=localhost
    REDIS_PORT=6379
 
+   # 원본 파일은 서버에 유지하고, 선택적 S3 mirror는 IAM Role로 PUT만 수행
+   FILE_STORAGE_TYPE=local
+   S3_BUCKET=your-s3-bucket
+   AWS_REGION=ap-northeast-2
+   S3_ENDPOINT=
+   S3_PATH_STYLE_ACCESS=false
+
    # 서버 포트
    PORT=5001
    WS_PORT=5002

apps/backend/README.md

@@ -91,6 +91,11 @@ make verify-java
 | `MONGO_URI` | ✅ | 없음 | MongoDB 연결 문자열              |
 | `REDIS_HOST` | ✅ | 없음 | Redis 호스트                    |
 | `REDIS_PORT` | ✅ | 없음 | Redis 포트                      |
+| `FILE_STORAGE_TYPE` | ❌ | `local` | 원본 파일 저장 방식. S3 mirror 모드에서도 `local` 유지 |
+| `S3_BUCKET` | ✅ | 없음 | 이미지 및 첨부 파일을 저장할 S3 버킷 |
+| `AWS_REGION` | ❌ | `ap-northeast-2` | S3 버킷 리전 |
+| `S3_ENDPOINT` | ❌ | 빈 값 | AWS S3 호환 스토리지의 사용자 지정 엔드포인트 |
+| `S3_PATH_STYLE_ACCESS` | ❌ | `false` | path-style S3 URL 사용 여부 |
 | `PORT` | ❌ | `5001` | HTTP API 포트 (`server.port`) |
 | `WS_PORT` | ❌ | `5002` | Socket.IO 서버 포트             |
 | `CORS_ALLOWED_ORIGINS` | ❌ | `*` | REST API CORS 허용 Origin 목록. 쉼표로 구분 |

apps/backend/docs/S3_DIRECT_UPLOAD.md

@@ -0,0 +1,37 @@
+# S3 PutObject mirror upload
+
+`NEXT_PUBLIC_FILE_UPLOAD_MODE=mirror`는 기존 multipart 업로드가 성공한 뒤 같은 파일을
+S3 `pending/mirror/`에 best-effort로 복제한다. 서비스 원본과 응답 계약은 기존 서버
+저장소를 유지하며, S3 실패는 사용자 업로드 성공을 되돌리지 않는다. 기본값은 `server`다.
+
+백엔드는 `FILE_STORAGE_TYPE=local`, `S3_BUCKET`, `AWS_REGION`을 사용한다. IAM Role에는
+`s3:PutObject`만 필요하고 애플리케이션은 미러 객체에 GET, HEAD, Copy, Delete를 호출하지
+않는다. AWS 자격증명은 이미지나 환경변수에 넣지 않는다.
+
+## Bucket CORS
+
+`https://frontend.example.com`을 실제 운영 origin으로 바꾸고 `*`는 사용하지 않는다.
+
+```json
+[
+  {
+    "AllowedOrigins": ["https://frontend.example.com"],
+    "AllowedMethods": ["PUT"],
+    "AllowedHeaders": ["content-type", "x-amz-*"],
+    "ExposeHeaders": ["ETag"],
+    "MaxAgeSeconds": 300
+  }
+]
+```
+
+`pending/` prefix 객체를 1일 후 삭제하는 lifecycle rule을 설정한다. PUT URL은 5분,
+MongoDB intent는 15분 후 만료된다.
+
+## Rollout
+
+1. 기존 서버 저장소가 정상인지 확인한다.
+2. 운영 이미지를 `--build-arg NEXT_PUBLIC_FILE_UPLOAD_MODE=mirror`로 빌드한다.
+3. `mirror_presign_success`, `mirror_put_success`, `mirror_put_failure`를 관찰한다.
+4. 문제가 생기면 프론트만 `server`로 다시 빌드한다.
+
+이 모드는 백엔드 업로드 부하를 제거하거나 S3를 영구 원본으로 사용하지 않는다.

apps/backend/monitoring/grafana/provisioning/dashboards/ktb-chat-monitoring.json

@@ -0,0 +1,70 @@
+{
+  "uid": "ktb-chat-monitoring",
+  "title": "KTB Chat Monitoring",
+  "tags": ["ktb", "loadtest"],
+  "timezone": "browser",
+  "schemaVersion": 39,
+  "version": 1,
+  "refresh": "5s",
+  "time": { "from": "now-15m", "to": "now" },
+  "templating": { "list": [] },
+  "panels": [
+    {
+      "id": 1,
+      "type": "stat",
+      "title": "Monitored targets",
+      "gridPos": { "h": 4, "w": 6, "x": 0, "y": 0 },
+      "targets": [{ "expr": "count(up{job!=\"cadvisor\"})", "legendFormat": "targets", "refId": "A" }],
+      "fieldConfig": { "defaults": { "unit": "none", "color": { "mode": "thresholds" }, "thresholds": { "mode": "absolute", "steps": [{ "color": "red", "value": null }, { "color": "green", "value": 1 }] } }, "overrides": [] },
+      "options": { "reduceOptions": { "calcs": ["lastNotNull"], "fields": "", "values": false }, "orientation": "auto", "textMode": "auto", "colorMode": "value" }
+    },
+    {
+      "id": 2,
+      "type": "timeseries",
+      "title": "HTTP requests / sec",
+      "gridPos": { "h": 8, "w": 18, "x": 6, "y": 0 },
+      "targets": [{ "expr": "sum by (status) (rate(http_server_requests_seconds_count{application=\"ktb-chat-backend\"}[1m]))", "legendFormat": "status {{status}}", "refId": "A" }],
+      "fieldConfig": { "defaults": { "unit": "reqps", "color": { "mode": "palette-classic" } }, "overrides": [] },
+      "options": { "legend": { "displayMode": "list", "placement": "bottom" }, "tooltip": { "mode": "multi" } }
+    },
+    {
+      "id": 3,
+      "type": "timeseries",
+      "title": "HTTP average latency",
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 8 },
+      "targets": [{ "expr": "sum(rate(http_server_requests_seconds_sum{application=\"ktb-chat-backend\"}[1m])) / sum(rate(http_server_requests_seconds_count{application=\"ktb-chat-backend\"}[1m]))", "legendFormat": "average", "refId": "A" }],
+      "fieldConfig": { "defaults": { "unit": "s" }, "overrides": [] },
+      "options": { "legend": { "displayMode": "list", "placement": "bottom" }, "tooltip": { "mode": "single" } }
+    },
+    {
+      "id": 4,
+      "type": "timeseries",
+      "title": "JVM heap used",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 8 },
+      "targets": [{ "expr": "sum(jvm_memory_used_bytes{application=\"ktb-chat-backend\",area=\"heap\"})", "legendFormat": "heap", "refId": "A" }],
+      "fieldConfig": { "defaults": { "unit": "bytes" }, "overrides": [] },
+      "options": { "legend": { "displayMode": "list", "placement": "bottom" }, "tooltip": { "mode": "single" } }
+    },
+    {
+      "id": 5,
+      "type": "timeseries",
+      "title": "JVM CPU",
+      "gridPos": { "h": 8, "w": 12, "x": 0, "y": 16 },
+      "targets": [{ "expr": "process_cpu_usage{application=\"ktb-chat-backend\"}", "legendFormat": "process", "refId": "A" }],
+      "fieldConfig": { "defaults": { "unit": "percentunit", "min": 0, "max": 1 }, "overrides": [] },
+      "options": { "legend": { "displayMode": "list", "placement": "bottom" }, "tooltip": { "mode": "single" } }
+    },
+    {
+      "id": 6,
+      "type": "timeseries",
+      "title": "MongoDB and Redis exporter up",
+      "gridPos": { "h": 8, "w": 12, "x": 12, "y": 16 },
+      "targets": [
+        { "expr": "up{job=\"mongodb\"}", "legendFormat": "mongodb", "refId": "A" },
+        { "expr": "up{job=\"redis\"}", "legendFormat": "redis", "refId": "B" }
+      ],
+      "fieldConfig": { "defaults": { "unit": "none", "min": 0, "max": 1 }, "overrides": [] },
+      "options": { "legend": { "displayMode": "list", "placement": "bottom" }, "tooltip": { "mode": "multi" } }
+    }
+  ]
+}

apps/backend/monitoring/prometheus/prometheus.dev.yml

@@ -13,7 +13,8 @@ scrape_configs:
 
   - job_name: 'spring-boot-app'
     metrics_path: '/actuator/prometheus'
-    scrape_interval: 5s
+    # Performance diagnostics need to see short-lived pool saturation spikes.
+    scrape_interval: 1s
     static_configs:
       - targets: ['host.docker.internal:5001']
         labels:
@@ -31,17 +32,3 @@ scrape_configs:
       - targets: ['redis-exporter:9121']
         labels:
           environment: 'dev'
-
-  - job_name: 'cadvisor'
-    static_configs:
-      - targets: ['cadvisor:8080']
-        labels:
-          environment: 'dev'
-    metric_relabel_configs:
-      # Extract container name from container_label_com_docker_compose_service
-      - source_labels: [container_label_com_docker_compose_service]
-        target_label: container_name
-      # Extract container name from id (fallback)
-      - source_labels: [id]
-        regex: '/docker/([a-f0-9]+)'
-        target_label: container_id

apps/backend/pom.xml

@@ -16,9 +16,17 @@
     <properties>
         <java.version>25</java.version>
         <spring-ai.version>2.0.0</spring-ai.version>
+        <aws-sdk.version>2.47.3</aws-sdk.version>
     </properties>
     <dependencyManagement>
         <dependencies>
+            <dependency>
+                <groupId>software.amazon.awssdk</groupId>
+                <artifactId>bom</artifactId>
+                <version>${aws-sdk.version}</version>
+                <type>pom</type>
+                <scope>import</scope>
+            </dependency>
             <dependency>
                 <groupId>org.springframework.ai</groupId>
                 <artifactId>spring-ai-bom</artifactId>
@@ -61,6 +69,10 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-actuator</artifactId>
         </dependency>
+        <dependency>
+            <groupId>software.amazon.awssdk</groupId>
+            <artifactId>s3</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.micrometer</groupId>
             <artifactId>micrometer-registry-prometheus</artifactId>

apps/backend/src/main/java/com/ktb/chatapp/config/MongoConfig.java

@@ -1,9 +1,29 @@
 package com.ktb.chatapp.config;
 
+import com.ktb.chatapp.model.MessageType;
+import java.util.List;
+import java.util.Locale;
+import org.springframework.context.annotation.Bean;
 import org.springframework.context.annotation.Configuration;
+import org.springframework.core.convert.converter.Converter;
 import org.springframework.data.mongodb.config.EnableMongoAuditing;
+import org.springframework.data.mongodb.core.convert.MongoCustomConversions;
+import org.springframework.data.convert.ReadingConverter;
 
 @Configuration
 @EnableMongoAuditing
 public class MongoConfig {
+
+    @Bean
+    MongoCustomConversions mongoCustomConversions() {
+        return new MongoCustomConversions(List.of(new MessageTypeReadConverter()));
+    }
+
+    @ReadingConverter
+    static class MessageTypeReadConverter implements Converter<String, MessageType> {
+        @Override
+        public MessageType convert(String source) {
+            return MessageType.valueOf(source.toLowerCase(Locale.ROOT));
+        }
+    }
 }

apps/backend/src/main/java/com/ktb/chatapp/config/MongoPoolMetricsConfig.java

@@ -0,0 +1,21 @@
+package com.ktb.chatapp.config;
+
+import io.micrometer.core.instrument.MeterRegistry;
+import io.micrometer.core.instrument.binder.mongodb.DefaultMongoConnectionPoolTagsProvider;
+import io.micrometer.core.instrument.binder.mongodb.MongoMetricsConnectionPoolListener;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+/**
+ * Supplies Micrometer's standard MongoDB pool listener. Spring Boot's Mongo metrics
+ * auto-configuration attaches this bean to the auto-configured MongoClient.
+ */
+@Configuration(proxyBeanMethods = false)
+public class MongoPoolMetricsConfig {
+
+    @Bean
+    MongoMetricsConnectionPoolListener mongoMetricsConnectionPoolListener(MeterRegistry registry) {
+        return new MongoMetricsConnectionPoolListener(
+                registry, new DefaultMongoConnectionPoolTagsProvider());
+    }
+}