diff --git a/README.md b/README.md
index 8b9b615..bd13aca 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,8 @@
 # 🌳 Welive
 
-[![Node.js](https://img.shields.io/badge/Node.js-20.x-339933?logo=node.js&logoColor=white)]()
-[![Express](https://img.shields.io/badge/Express-5.1-000000?logo=express&logoColor=white)]()
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)]()
-[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?logo=postgresql&logoColor=white)]()
-[![Prisma](https://img.shields.io/badge/Prisma-6.18-2D3748?logo=prisma&logoColor=white)]()
-[![Docker](https://img.shields.io/badge/Docker-Build%20%26%20Deploy-2496ED?logo=docker&logoColor=white)]()
-[![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-CI%2FCD-2088FF?logo=githubactions&logoColor=white)]()
-[![AWS](https://img.shields.io/badge/AWS-EC2%20%7C%20S3-F8991C?logo=amazon-aws&logoColor=white)]()
+<p align="center">
+  <img src="./docs/assets/logo.png" width="220" alt="Welive Logo" />
+</p>
 
 ## 📌 프로젝트 소개
 
@@ -15,491 +10,531 @@
 위리브(Welive)는 입주민과 관리 단체가 한자리에서 소통하고 문제를 해결하며, 더 나은 공동체를 만들어가는 아파트 상호 관리 플랫폼입니다.  
 당신의 일상이 더 편해지는 그 순간까지, 위리브가 함께합니다.
 
----
-
-## 📋 프로젝트 개요
+## 🔗 데모 & 주요 링크
 
-- **프로젝트 기간**: 2025.10.17 ~ 2025.11.28
-- **목표**: 레이어드 아키텍처 기반의 안정적이고 확장 가능한 프로젝트 관리 백엔드 구축
-- **주요 기능**:
-- 사용자 인증 및 승인 프로세스  
-  - 슈퍼관리자 / 관리자 / 입주민의 역할 기반 승인 구조 및 2차 인증  
-  - (관리자·입주민 승인 요청, 승인/거절, 자동 매칭)
+- Frontend: https://welive.mimu.live
+- Backend: https://api.mimu.live
+- Swagger 문서: https://api.mimu.live/api/docs
+- GitHub Repository: https://github.com/codeit-welive/welive
+- 최종 발표 자료: 준비 중
+- 시연 영상: 준비 중
+- 팀 노션 문서: 준비 중
 
-> [!NOTE]  
-> 인증은 **JWT Access / Refresh Token** 기반으로 동작하며, Refresh Token은 DB에서 상태를 관리해 로그아웃·재발급 시 기존 토큰을 무효화하도록 설계했습니다.
+## 🛠 기술 스택
 
-- 입주민 명부 관리  
-  - 개별 등록 / CSV 업로드 / 검색·필터·페이지네이션 / 일괄 정리 기능 제공
+### Backend
+[![Node.js](https://img.shields.io/badge/Node.js-20.x-339933?logo=node.js&logoColor=white)]()
+[![Express](https://img.shields.io/badge/Express-5.x-000000?logo=express&logoColor=white)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)]()
+[![Prisma](https://img.shields.io/badge/Prisma-ORM-2D3748?logo=prisma&logoColor=white)]()
+[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-17-4169E1?logo=postgresql&logoColor=white)]()
 
-> [!WARNING]  
-> CSV 업로드 시 **헤더 명칭이 정확히 일치**해야 하며, 인코딩은 **UTF-8**만 지원됩니다.  
-> 잘못된 칼럼 또는 누락이 있는 경우, 해당 파일은 전체 업로드가 거부됩니다.
+### Infra / DevOps
+[![Docker](https://img.shields.io/badge/Docker-Containerization-2496ED?logo=docker&logoColor=white)]()
+[![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-CI/CD-2088FF?logo=githubactions&logoColor=white)]()
+[![AWS EC2](https://img.shields.io/badge/AWS-EC2-F8991C?logo=amazonaws&logoColor=white)]()
+[![AWS S3](https://img.shields.io/badge/AWS-S3-569A31?logo=amazonaws&logoColor=white)]()
+[![Nginx](https://img.shields.io/badge/Nginx-Reverse_Proxy-009639?logo=nginx&logoColor=white)]()
 
-- 민원(문의) 관리  
-  - 상태(처리 전·중·완료) 변경, 실시간 알림, 비공개 처리, 수정·삭제 제한 로직 포함
-- 주민 투표 시스템  
-  - 투표권자 범위 설정, 일정 기반 자동 오픈/마감, 결과 자동 공지 등록, 실시간 참여 가능
+### Testing & Quality
+[![Jest](https://img.shields.io/badge/Jest-Testing-C21325?logo=jest&logoColor=white)]()
+[![Supertest](https://img.shields.io/badge/Supertest-HTTP_Testing-75AADB)]()
+[![ESLint](https://img.shields.io/badge/ESLint-Linting-4B32C3?logo=eslint&logoColor=white)]()
+[![Prettier](https://img.shields.io/badge/Prettier-Formatting-F7B93E?logo=prettier&logoColor=black)]()
 
-- 공지사항 및 일정 관리  
-  - 카테고리, 중요도, 댓글, 조회수, 일정 자동 반영 등 관리자 중심의 공지 운영 기능
-- 댓글 시스템  
-  - 공지/민원 기반 댓글 등록·수정·삭제 기능 제공
-- 알림 시스템 (SSE)  
-  - 민원·공지·투표 상태 변경 시 실시간 알림 전송
-- 파일 업로드 (프로필 사진)  
-  - S3 업로드 기반의 안정적인 이미지 처리
+### Frontend (협업 / 참고)
+[![Next.js](https://img.shields.io/badge/Next.js-Frontend-000000?logo=nextdotjs&logoColor=white)]()
 
-> [!WARNING]
-> 업로드된 파일은 확장자가 아니라 **실제 바이너리(Magic Number)** 기반으로 검증되며,  
-> 이미지가 아닌 파일을 위장하여 업로드할 경우 서버에서 즉시 차단됩니다.
+---
 
-    - DB 트랜잭션 및 동시성 최적화 구조 설계  
-      - 대량 업로드(CSV), 투표 마감 스케줄러 등에서의 트랜잭션 혹은 동시성 제한 처리 및 성능 고려
+### 🧭 기술 스택 채택 이유
 
-      > [!NOTE]
-      > Poll 자동 활성화/만료 로직은 **Limiter 기반 동시성 제어**로 보호되며,  
-      > 동일 Poll에 대한 중복 스케줄 실행은 자동으로 방지됩니다.
+**Node.js + Express 5**
+- 대규모 서비스에서도 검증된 경량 웹 프레임워크로, 라우팅·미들웨어 기반 구조를 세밀하게 설계하기 용이함  
+- 비동기 I/O 기반으로 SSE·Socket.io 등 실시간 기능 구현에 적합  
+- Layered Architecture 구성 시 Router → Controller → Service → Repository 흐름을 가장 유연하게 설계할 수 있음
 
----
+**TypeScript**
+- 도메인 단위로 타입을 엄격하게 정의해 대규모 모듈 간 의존성을 안정적으로 유지  
+- DTO·Validator·Repository 등 계층 간 데이터 계약을 명확히 보장  
+- Prisma와 결합하여 컴파일 단계에서 DB 스키마 오류를 조기 감지할 수 있음
 
-## 👥 팀 구성 및 역할
+**Prisma + PostgreSQL**
+- Prisma의 스키마 기반 ORM은 모델 변경 및 마이그레이션 관리가 직관적이며, 대규모 테이블 조인 구조에서도 타입 안전성을 제공  
+- PostgreSQL은 트랜잭션 강도가 높아 Poll Scheduler·알림·대량 CSV 처리 등 동시성 요구에 안정적으로 대응
 
-| 담당자                                      | 역할                                     | 담당 모듈                                                                         | 주요 책임                                                                                              |
-| ------------------------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| [유진호(리드)](https://github.com/selentia) | Backend Lead · System Architect · DevOps | Core, Infra/DevOps, Users,  Notifications/SSE, Poll Scheduler, 전체 스키마 | 시스템 아키텍처 및 스키마 설계 / Core·서버 파이프라인 구축 / 일부 도메인 개발 및 테스트·배포 환경 구축 / 프로젝트 문서·산출물(요구·설계·구현·테스트·배포) 및 시연 영상 통합 정리 |
-| [한선재(팀장)](https://github.com/HSunJ)    | Auth & Residents & Apartments            | Auth, Residents, Apartments                                                       | Auth 기능 전반 구현 / Residents·Apartments CRUD·CSV / 입주민·아파트 권한 로직                          |
-| [김준철](https://github.com/nodejun)        | Complaints & Comments & Chat             | Complaints, Comments, Chat(Socket.io)                                             | Complaints·Comments CRUD / 실시간 Chat API 개발                                                        |
-| [김나연](https://github.com/luciakim22)     | Polls & Notices                          | Polls, PollsVote, Notices, Events                                                 | Polls·PollsVote CRUD / Notices CRUD, Events CRUD                                                                |
+**Docker + Nginx**
+- 개발·테스트·운영 환경을 완벽하게 동일하게 유지할 수 있어 배포 안정성이 높음  
+- Nginx Reverse Proxy를 통해 SSL, 정적 자원 서비스, CORS, 헤더 보안 등을 단일 진입점에서 제어 가능  
+- BE(컨테이너) + FE(PM2) 조합으로 초기 로딩 시간을 최적화하면서도 CI/CD 자동화에 유리
 
----
+**AWS(EC2, S3)**
+- EC2는 Docker 환경 배포에 직관적이며 확장 및 유지보수가 용이  
+- S3는 이미지·정적 파일 저장에 안정적이며, Presigned URL 기반 업로드로 보안 수준을 크게 높일 수 있음
 
-## 🛠 기술 스택
+**GitHub Actions + GHCR**
+- 푸시 이벤트 기반으로 테스트 → 빌드 → 이미지 생성 → 서버 자동 배포까지 완전 자동화  
+- GHCR 사용으로 이미지 버전 관리 및 롤백이 용이하며, 사설 레지스트리보다 설정이 단순
 
-### ⚙️ 백엔드 서버
-
-| 구분                        | 기술                                                                                                              |
-| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| **언어/런타임**             | TypeScript, Node.js(Express 5)                                                                                    |
-| **서버 프레임워크·구조**    | Express 5 기반 커스텀 서버(app.ts), 라우터 모듈 구조, 미들웨어 파이프라인 설계                                    |
-| **ORM/DB**                  | Prisma, PostgreSQL                                                                                                |
-| **스케줄러**                | cron (투표 활성화/만료 작업), **Limiter 기반 Poll Scheduler(직접 구현)**                                          |
-| **유효성 검증**             | Zod(DTO·Body·Query·Params, CSV 데이터 검증 포함)                                                                  |
-| **입력 정화(Sanitize)**     | isomorphic-dompurify + jsdom                                                                                      |
-| **파일 업로드/이미지 처리** | multer, sharp                                                                                                     |
-| **AWS 연동**                | AWS SDK v3 (@aws-sdk/client-s3, credential-providers, s3-request-presigner) — S3 업로드                           |
-| **보안/안정화**             | helmet(CSP 포함), hpp, express-rate-limit, CORS(화이트리스트 기반), bcrypt(+pepper), jsonwebtoken(access/refresh) |
-| **로그/모니터링**           | Pino(애플리케이션 로그), Morgan(HTTP 요청 로그)                                                                   |
-| **환경변수 관리**           | dotenv, dotenv-cli, cross-env                                                                                     |
+**Jest + Supertest**
+- DB 연동 테스트, SSE 전달 테스트, 스케줄러 동작까지 검증 가능한 구조  
+- 테스트 DB를 별도로 구성해 실제 Prisma 트랜잭션 흐름을 그대로 재현 가능  
 
 ---
 
-### 🧪 개발 및 테스트
+### 🧩 주요 패키지 채택 이유
 
-| 구분                   | 기술                                |
-| ---------------------- | ----------------------------------- |
-| **테스트 프레임워크**  | Jest, ts-jest                       |
-| **HTTP 테스트**        | supertest                           |
-| **모킹/도구**          | jest.mock, jsdom                    |
-| **정적 분석**          | ESLint, TypeScript ESLint, Prettier |
-| **경로/빌드 유틸리티** | tsc-alias, tsconfig-paths, rimraf   |
+- **Zod**: DTO/Query/Params를 스키마 기반으로 통합 관리하여 검증 일관성을 보장  
+- **DOMPurify + jsdom**: 서버단 Sanitization으로 XSS 공격 차단 (FE에서 조작하더라도 무효화)  
+- **sharp**: 이미지 리사이즈 및 Magic Number 기반 MIME 검증을 통한 파일 위장 공격 방지  
+- **Limiter(직접 구현)**: Poll 스케줄러 동시성 제어(단일 실행 보장)  
+- **Socket.io / SSE**: 채팅 + 실시간 알림 각각의 특성을 활용한 이중 실시간 처리 구조  
 
 ---
 
-### 🏗 운영·배포(Infra / DevOps)
+## 🚀 핵심 기능 요약
 
-| 구분                          | 기술                                                    |
-| ----------------------------- | ------------------------------------------------------- |
-| **컨테이너/배포**             | Docker, docker-compose, GitHub Actions(CI/CD 자동 배포) |
-| **리버스 프록시**             | Nginx                                                   |
-| **백엔드 프로세스 실행 방식** | Docker 컨테이너 단일 실행 (PM2 미사용)                  |
-| **프론트엔드 배포(참고)**     | Next.js → PM2 기반 프로세스 실행                        |
-| **로깅/운영**                 | Pino 로그, Nginx Access/Error 로그                      |
+- **역할 기반 인증/승인 프로세스**  
+  - 입주민 · 관리자 · 슈퍼관리자 등 역할별 회원가입, 승인 요청, 승인/거절 흐름
 
----
+- **입주민 명부 관리**  
+  - CSV 업로드, 검색/필터링, 페이징, 일괄 정리 기능 제공
 
-### 🧰 개발 편의
+- **공지사항 / 민원 / 댓글 시스템**  
+  - CRUD, 카테고리, 조회수, 비공개 처리, 수정 제한 등 운영 기능 포함
 
-| 구분                            | 기술                                |
-| ------------------------------- | ----------------------------------- |
-| **자동 재시작**                 | nodemon                             |
-| **동시 실행 스크립트**          | concurrently                        |
-| **Swagger 문서 자동 생성/서빙** | swagger-autogen, swagger-ui-express |
+- **실시간 알림 시스템 (SSE)**  
+  - 민원/공지/투표 상태 변경 시 즉시 알림 이벤트 전달
 
-## 📂 디렉터리 구조
+- **주민 투표 시스템 (Polls)**  
+  - 투표권자 범위 설정, 자동 오픈/마감, 실시간 참여, 결과 자동 집계
 
-프로젝트 전체 구조는 대규모이기 때문에, 주요 책임 단위 중심으로 요약한 형태입니다.
+- **이벤트 캘린더 (관리자용)**  
+  - 아파트 내 일정 관리 및 공지와 연동되는 이벤트 CRUD 제공
 
-```
-welive/
-├── .github/workflows/ # CI/CD 파이프라인 (CI, CD)
-├── infra/ # 배포/인프라 구성
-│ ├── docker/ # Dockerfile, docker-compose, 서버 구성
-│ └── nginx/ # Nginx Reverse Proxy 설정
-│
-├── prisma/ # Prisma 스키마 & 마이그레이션
-│ ├── schema.prisma
-│ ├── migrations/
-│ └── seed.ts
-│
-├── public/ # 정적 파일 (템플릿 등)
-│ └── templates/
-│
-├── scripts/ # Swagger 자동 생성 등 스크립트
-│ ├── genSwagger.js
-│ └── pinTree.js
-│
-├── src/
-│ ├── @types/ # Express 타입 확장
-│ │
-│ ├── common/ # 공통 유틸/상수/Error/Helper
-│ │ ├── constants/
-│ │ ├── errors/
-│ │ └── helpers/
-│ │
-│ ├── core/ # 앱 코어 레이어
-│ │ ├── aws/ # S3 업로드/삭제 유틸
-│ │ ├── files/ # 파일 MIME/MagicNumber 검증
-│ │ ├── health/ # /health API
-│ │ ├── middlewares/ # 인증/CORS/CSV/Error 핸들러
-│ │ ├── sanitize/ # 입력 정화(DOMPurify)
-│ │ ├── socket/ # Socket.io 초기화
-│ │ ├── sse/ # SSE 라우터/Emitter
-│ │ ├── utils/ # Limiter, Zod wrapper 등
-│ │ ├── app.ts # Express 앱 초기화
-│ │ ├── env.ts # 환경 변수 로더(Zod 검증)
-│ │ ├── httpLogger.ts
-│ │ ├── logger.ts
-│ │ ├── prisma.ts
-│ │ └── router.ts
-│ │
-│ ├── jobs/ # Poll Scheduler(자동 활성화/만료)
-│ │ └── poll/
-│ │
-│ ├── modules/ # 도메인 모듈 (Router·Service·Repo·Validator·Dto)
-│ │ ├── apartments/
-│ │ ├── auth/
-│ │ ├── chats/
-│ │ ├── comments/
-│ │ ├── complaints/
-│ │ ├── events/
-│ │ ├── notices/
-│ │ ├── notifications/
-│ │ ├── poll-scheduler/
-│ │ ├── polls/
-│ │ ├── residents/
-│ │ └── users/
-│ │
-│ └── index.ts # 서버 엔트리
-│
-├── swagger/ # Swagger JSON 결과물
-│
-├── tests/ # 통합 테스트 및 Core 테스트
-│ ├── core/
-│ ├── modules/
-│ ├── jobs/
-│ └── setup/
-│
-├── logs/ # 서버/테스트 로그
-├── .env* # 환경 변수 파일들
-├── jest.config.ts
-├── tsconfig.json
-└── package.json
+- **실시간 채팅 (Socket.io)**  
+  - 입주민–관리자 간 빠른 응대를 위한 실시간 메시징 기능
 
-```
+- **프로필 이미지 업로드 (S3 Presigned URL)**  
+  - Magic Number 기반 검증으로 위장 파일 차단, 안전한 파일 처리
 
----
+- **동시성 제어 기반 스케줄러 (Limiter)**  
+  - Poll 자동 활성화/만료 시 단일 실행 보장 및 경쟁 조건 방지
 
-## ⚙️ 실행 방법
+> 위리브는 학습용 예제가 아니라, 실제 아파트 관리 도메인을 고려한  
+> ‘기능·보안·확장성 중심의 실전 프로젝트’로 설계되었습니다.
 
-### 1) 환경 변수 예시 (`.env.example`)
+## 🏛 시스템 아키텍처
 
-`.env.example` 파일을 참고하여 실제 환경에 맞게 `.env`, `.env.production`, `.env.test` 파일을 구성합니다.
+```mermaid
+flowchart LR
+    subgraph CLIENT["Client"]
+        A[Browser / Next.js]
+    end
 
-```env
-# DATABASE
-DATABASE_URL=postgresql://<user_name>:<password>@localhost:5432/welive
+    subgraph PROXY["Nginx Reverse Proxy"]
+        B[Nginx]
+    end
 
-# PORT
-PORT=3001
-FE_PORT=3000
+    subgraph BACKEND["Backend (Node.js · Express 5)"]
+        C[Router]
+        D[Controller]
+        E[Service]
+        F[Repository]
+        G[Prisma Client]
+    end
 
-# BASE URL (API 오리진)
-BASE_URL=https://your.domain.com
+    subgraph DATABASE["PostgreSQL (RDS)"]
+        H[(PostgreSQL)]
+    end
 
-# FRONT (프론트엔드 오리진)
-FRONT_URL=https://your.domain.com
+    subgraph STORAGE["AWS S3"]
+        S3[S3 Bucket - Profile Images]
+    end
 
-# RUNTIME
-CORS_ORIGIN=https://your.domain.com
-ACCESS_TOKEN_SECRET=your_accesstoken_secret
-REFRESH_TOKEN_SECRET=your_refreshtoken_secret
-PASSWORD_PEPPER=your_password_pepper
-DEFAULT_AVATAR_URL=https://your_bucket_name.s3.ap-northeast-2.amazonaws.com/default_avatar.png
+    subgraph CICD["CI/CD Pipeline"]
+        GA[GitHub Actions]
+        GHCR[GHCR - Docker Image]
+        EC2[EC2 - Docker Runtime]
+    end
 
-# AWS S3
-AWS_REGION=ap-northeast-2
-AWS_S3_BUCKET_NAME=your_bucket_name
-AWS_S3_BASE_URL=https://your_bucket_name.s3.ap-northeast-2.amazonaws.com
+    %% Client -> Backend
+    A --> B --> C
+    C --> D --> E --> F --> G --> H
+
+    %% File Upload
+    E -->|Upload/Delete| S3
+
+    %% CI/CD Flow
+    GA --> GHCR --> EC2 --> B
 ```
 
-> [!WARNING]
-> 테스트 환경(`.env.test`)은 Jest 스크립트 실행 시 자동으로 로드되며,  
-> 테스트용 DB는 `test:reset`/`test:migrate` 과정에서 초기화됩니다.  
-> 운영 DB 연결 정보가 `.env.test`에 들어가지 않도록 반드시 주의해야 합니다.  
+## 🗂 Database ERD
 
-### 2) 패키지 설치
+<p align="center">
+  <img src="./docs/assets/erd.png" width="100%" alt="Welive ERD" />
+</p>
 
-```bash
-npm install
-```
+### 📌 주요 테이블 관계 요약
 
-### 3) 데이터베이스 설정 (Prisma)
+- **Apartments → Residents** : 한 아파트에는 여러 입주민이 소속  
+- **Residents → Complaints / Notices / Comments** : 입주민이 작성한 민원·공지·댓글과 연결  
+- **Polls → PollVotes** : 투표 1개에 여러 투표 기록이 종속  
+- **Complaints / Notices / Polls → Events** : 모든 주요 활동은 이벤트 로그로 기록  
+- **Events → Notifications** : 상태 변경 시 알림(SSE)로 연동  
+- **Users → Residents** : 주민 계정과 사용자 계정의 1:1 매핑 구조  
 
-개발/테스트 환경 모두 Prisma 스키마를 기반으로 초기화해야 합니다.
+> ERD는 Prisma Schema 기반으로 자동 생성되며,  
+> 관계형 모델을 통해 권한/역할 기반 관리, 실시간 알림, 투표 시스템 등  
+> 주요 기능을 일관된 구조로 확장할 수 있도록 설계했습니다.
 
-```bash
-# 마이그레이션 + 시드 전체 수행
-npm run prisma:migrate
-
-# 또는 개별 실행:
-npm run prisma:generate     # 프리즈마 클라이언트 생성
-npm run prisma:reset        # DB 초기화 (dev)
-npm run seed                # seed.ts 실행
-npm run prisma:studio       # Prisma Studio(웹 기반 DB UI)
-```
+## 🏗 시스템 구조 (Layered Architecture)
 
-### 4) 개발 서버 실행
+위리브 백엔드는 **Express 5 기반의 Layered Architecture**로 구성되어 있으며,  
+각 레이어가 명확한 역할을 가지도록 설계해 유지보수성과 확장성을 높였습니다.
 
-이 프로젝트는 백엔드(Express), 프론트엔드(Next.js) 를 동시에 개발하기 위해 `concurrently`를 사용합니다.
+### 🔹 Layer 구성
 
-```bash
-npm run dev
-```
+- **Router Layer**
+  - 요청 엔드포인트 정의 및 모듈 단위 라우팅 구성  
+  - 인증/인가, CSV 검증, Sanitization 등 공통 미들웨어 적용 지점
 
-#### 개별 실행 방법
+- **Controller Layer**
+  - HTTP 요청/응답 처리  
+  - 서비스 호출 전 입력값 검증(Zod) 및 예외 흐름 통제  
+  - Swagger 자동 문서화 주석 위치
 
-**백엔드 단독 실행**
+- **Service Layer**
+  - 비즈니스 로직 중심  
+  - 권한 검증, 트랜잭션 처리, 도메인 규칙 적용  
+  - SSE 알림 트리거, Poll 스케줄러 호출 등 핵심 로직 담당
 
-```bash
-npm run dev:be
-```
+- **Repository Layer**
+  - Prisma 기반 데이터베이스 접근  
+  - 복잡한 쿼리/조인/트랜잭션을 캡슐화하여 Service와 분리
 
-**프론트 단독 실행**
+- **Prisma Client Layer**
+  - PostgreSQL과 직접 통신  
+  - 타입 세이프티 제공 및 스키마 기반 모델 관리
 
-```bash
-npm run dev:fe
-```
+### 🔹 추가 서브 시스템
 
-### 5) 테스트 실행
+- **Input Sanitization (DOMPurify + jsdom)**  
+  댓글/공지/민원 등 사용자 입력 필드에 대해 서버 단에서 HTML 정화 수행
 
-jest 환경은 `.env.test`를 자동 로드하며,  
-Prisma 테스트 DB는 `test:migrate`/`test:reset`으로 제어할 수 있습니다.
+- **Validation Layer (Zod)**  
+  Params/Query/Body를 스키마 기반으로 통합 검증하여 Controller에 도달하기 전 데이터 무결성 보장
 
-```bash
-npm test            # 전체 테스트 실행 (--runInBand)
-npm run test:watch  # 변경 감지
-npm run test:cov    # 테스트 커버리지
-```
+- **SSE Notification Layer**  
+  알림 emitter를 별도 모듈로 분리해 Poll/민원/공지 등의 이벤트를 실시간으로 전송
 
-테스트용 DB 초기화:
+- **Poll Scheduler (Limiter 기반 단일 실행 보장)**  
+  Poll 자동 오픈/만료를 Cron + Limiter 조합으로 구현해 경쟁 조건을 방지
 
-```bash
-npm run test:reset
-npm run test:migrate
-```
+- **Socket Layer (실시간 채팅)**  
+  입주민–관리자 간 실시간 메시징을 Socket.io로 처리 (JWT 인증 미들웨어 포함)
 
-> [!WARNING]
-> 테스트 초기화(`test:reset`)는 테스트용 DB를 전부 비우고 마이그레이션을 다시 적용하므로,  
-> 실제 데이터가 저장된 DB와는 반드시 분리된 환경에서 실행해야 합니다.
+> 이 레이어 구조는 **도메인 확장·테스트·보안·배포**의 모든 과정에서 일관된 흐름을 유지하며,  
+> 대규모 서비스 구조로 확장해도 안정적으로 유지될 수 있도록 설계되었습니다.
 
-### 6) 빌드
+## 🔐 보안 설계 (Security Overview)
 
-```bash
-npm run build
-```
+위리브는 **Express 5 기반 다층 보안 구조**를 적용해  
+입력 검증부터 파일 업로드, 인증, 서버 헤더까지 전반적인 보안 리스크를 최소화했습니다.
 
-빌드를 수행하면 `dist/` 디렉터리가 생성되고,
-`tsc-alias`로 경로 alias가 자동 변환됩니다.
+### 🔹 HTTP 보안 헤더 & 서버 보호
+- **helmet(CSP 적용)**: 스크립트/이미지/프레임 정책 강화로 XSS·Clickjacking 방지  
+- **X-Powered-By 제거**, **ETag 비활성화**로 프레임워크 노출 및 캐싱 기반 공격 완화  
+- **HPP(HTTP Parameter Pollution) 차단** 적용
 
-### 7) 프로덕션 실행
+### 🔹 인증 & 권한
+- **JWT Access / Refresh Token 구조**  
+- Refresh Token은 **DB 상태 관리 방식**으로 구현해 재발급 시 기존 토큰 무효화  
+- 라우터 단위로 **역할 기반 접근 제어(Role-based Access Control)** 적용
 
-프론트는 PM2로 실행하고,  
-백엔드는 Docker 기반으로 운영하는 환경과 PM2 기반 환경 모두 지원하도록 스크립트가 구성되어 있습니다.  
+### 🔹 CORS & Proxy 환경
+- Strict Origin 기반 CORS 화이트리스트  
+- `trust proxy` 설정으로 Nginx 뒤에서 IP/프로토콜 정보 정확히 파싱
 
-**PM2 기반 실행 (로컬 / 서버 공용)**
+### 🔹 입력 검증 & Sanitization
+- **Zod 스키마** 기반 Params/Query/Body 정형적 검증  
+- 사용자 입력값은 **DOMPurify + jsdom** 기반 서버단 Sanitization으로 XSS 차단  
+- CSV 업로드 시 **정확한 헤더·타입 검증 및 전체 트랜잭션 처리**
 
-```bash
-npm start     # (= start:be && start:fe)
-```
+### 🔹 파일 업로드 보안
+- 이미지 업로드는 확장자가 아닌 **Magic Number(MIME) 기반 검증**  
+- sharp를 이용한 **강제 재인코딩(재압축)으로 “폴리글롯(polyglot) 파일” 차단**  
+  - 예: JPEG/PNG로 위장한 스크립트·실행파일 혼합 페이로드 강제 제거  
+- 재인코딩 후에만 Presigned URL 기반 S3 업로드 허용  
+- 위장 파일(예: PNG 헤더 + JS 페이로드) 즉시 거부
 
-**백엔드만 실행**
+### 🔹 Rate Limiting & 서버 보호
+- **express-rate-limit**: IP 단위 요청 제한 적용  
+- JSON Body 사이즈 제한(2MB), URL-encoded 제한
 
-```bash
-npm run start:be
-```
+### 🔹 실시간 통신 보호
+- **SSE 알림**: JWT 기반 인증  
+- **Socket.io 채팅**: Connection middleware로 인증 후 소켓 확립
 
-**프론트만 실행**
+### 🔹 에러/로깅
+- Pino 기반 구조적 로깅  
+- 글로벌 에러 핸들러로 내부 스택 숨김 & 일관된 에러 응답 포맷 유지
 
-```bash
-npm run start:fe
-```
+> 입력 검증, Sanitization, 재인코딩 기반 파일 보안, JWT 인증, CSP 등  
+> 여러 보안 계층을 적용하여 안정성과 신뢰성을 강화했습니다.
 
-**중지:**
+## 🚢 CI/CD & 배포 구조
 
-```bash
-npm run stop
-```
+위리브는 **Docker 기반 프로덕션 환경 + GitHub Actions 자동 배포 파이프라인**을 구축하여  
+개발 → 빌드 → 테스트 → 배포의 전 과정을 자동화했습니다.
 
-> [!WARNING]
-> `npm run stop` 스크립트는 `pm2 delete` 실패 시에도 프로세스를 계속 진행하도록 구성되어 있습니다.  
-> PM2 프로세스가 수동으로 종료된 상태라면 경고가 출력될 수 있지만, 이는 정상 동작입니다.  
+### 🔹 CI/CD 흐름
 
-### 8) Swagger 문서 생성
+1. **GitHub Actions(CI)**
+   - PR/commit 시 자동으로 테스트 실행(Jest)
+   - 타입 체크/ESLint 검사 통해 품질 유지
+   - 모든 테스트 통과 시 Docker 이미지 빌드
 
-Swagger는 자동 생성 스크립트(genSwagger.js) 를 통해 /swagger/swagger.json으로 빌드됩니다.
+2. **GHCR(GitHub Container Registry)**
+   - 빌드된 Docker 이미지를 태그 버전으로 업로드  
+   - 이미지 버전 관리 및 롤백이 용이
 
-```bash
-npm run swagger:generate
-```
+3. **GitHub Actions(CD) – EC2 자동 배포**
+   - SSH를 통해 EC2에 접속  
+   - 최신 이미지 Pull  
+   - `docker-compose.prod.yaml` 기반으로 컨테이너 재기동  
+   - 환경 변수 파일(.env.prod) 자동 생성/동기화
 
-이후 /api/docs 경로에서 Swagger UI로 확인할 수 있습니다.
+4. **EC2(Docker Runtime)**
+   - Backend 컨테이너 단일 실행  
+   - 로그 관리(Pino 파일 저장), 헬스체크 포함
 
-> [!NOTE]
-> `swagger/swagger.json` 파일이 존재하지 않는 경우, 서버는 부정확한 문서 상태로의 배포를 막기 위해 즉시 종료되도록 설계되어 있습니다.  
-> 배포 전에 반드시 `npm run swagger:generate`를 실행해야 합니다.  
+5. **Nginx Reverse Proxy**
+   - 요청 라우팅: `FE → / (Next.js)` / `BE → /api`  
+   - Cloudflare Origin 복원, gzip 압축, CORS/보안 헤더 일괄 관리  
+   - SSL(TLS) 종단 처리
 
----
+### 🔹 배포 구조 요약
 
-## 🔐 보안 기본 설정
+```mermaid
+flowchart LR
+    Dev[Developer Push] --> GA[GitHub Actions]
+    GA --> Test[Tests & Lint]
+    GA --> Build[Docker Build]
+    Build --> GHCR[Push to GHCR]
+    GHCR --> Deploy[GA Deploy Script]
+    Deploy --> EC2[(EC2)]
+    EC2 --> DC[Docker Compose Up]
+    DC --> Nginx[Nginx Reverse Proxy]
+    Nginx --> Backend[Backend Container]
+```
 
-WeLive 서버는 Express 5 기반으로, 다음과 같은 다층 보안 요소를 적용하여 안정성과 안전성을 강화했습니다.
+### 🔹 주요 특징
 
-### 1) HTTP 보안 헤더
+- **완전 자동 배포**: Git push만으로 테스트 → 빌드 → 배포까지 자동 처리  
+- **환경 분리**: `.env`, `.env.test`, `.env.production` 분리 로드  
+- **선택적 재배포**: API 변경 없이 특정 모듈만 재배포 가능  
+- **에러 방지 장치**: Swagger 미생성 시 서버 기동 차단, 프록시/포트 자동 검증  
+- **운영 안정성 강화**: Docker 이미지 기반으로 동일한 실행 환경 보장  
 
-- **helmet** 적용
-  - CSP(Content Security Policy) 커스텀 구성
-  - `frame-ancestors: none`, `object-src: none` 등 클릭재킹 및 위변조 방지
-  - 개발 환경에서만 `img-src`에 `blob:` 허용
+## 📂 디렉터리 구조 (요약)
 
-### 2) X-Powered-By & ETag 제거
+프로젝트는 **Layered Architecture + 도메인 모듈 구조**로 구성되어 있으며,  
+핵심 책임 단위가 명확하게 분리되어 유지보수성과 확장성을 높였습니다.
 
-- `app.disable('x-powered-by')` 로 Express 노출 제거
-- `app.set('etag', false)` 로 ETag 기반 캐싱 무효화 (보안 취약점 완화)
+```
+welive/
+├── infra/ # Docker, nginx, 배포 설정
+│ ├── docker/
+│ └── nginx/
+│
+├── prisma/ # Prisma 스키마 및 마이그레이션
+│ ├── schema.prisma
+│ └── migrations/
+│
+├── src/
+│ ├── core/ # 앱 코어 (env·logger·middlewares·sse·socket 등)
+│ ├── modules/ # 도메인 모듈 (auth, residents, polls, notices 등)
+│ ├── jobs/ # Poll Scheduler
+│ ├── @types/ # 글로벌 타입 확장
+│ └── index.ts # 서버 엔트리포인트
+│
+├── tests/ # Core / Modules / Scheduler 통합 테스트
+│ ├── core/
+│ ├── modules/
+│ └── jobs/
+│
+├── swagger/ # 자동 생성된 Swagger JSON
+├── scripts/ # Swagger 생성 등 스크립트
+└── package.json
+```
 
-### 3) Rate Limiting (요청 제한)
+### 📌 구조 특징
+- **core**: 인증/CORS/Sanitize/Error 핸들러, SSE, Socket, Limiter 등 공통 시스템 레이어  
+- **modules**: Router → Controller → Service → Repository → Prisma 구조를 따르는 도메인 단위 구현  
+- **jobs**: Poll 자동 오픈/만료 스케줄러  
+- **tests**: 실제 DB 기반 통합 테스트 (테스트용 DB 자동 초기화)
 
-- **express-rate-limit** 적용
-  - 15분 기준 최대 1000 요청
-  - 표준 헤더 적용(429 메시지 개선)
+## ⚙️ 실행 가이드 (Run & Setup Guide)
 
-### 4) HTTP Parameter Pollution 방지
+### 1) 환경 변수 설정 (`.env`)
+`.env.example` 파일을 참고해 개발/테스트/운영 환경에 맞게 `.env`, `.env.test`, `.env.production`을 구성합니다.
 
-- **hpp** 사용
-  - 중복된 파라미터로 인한 HPP 공격 차단
+```env
+# DATABASE
+DATABASE_URL=postgresql://<user>:<password>@localhost:5432/welive
 
-### 5) CORS 화이트리스트 기반 제한
+# SERVER
+PORT=3001
+FE_PORT=3000
+CORS_ORIGIN=http://localhost:3000
 
-- 환경 변수 기반 **정적 오리진 화이트리스트 구성**
-- 인증 쿠키 및 JWT 헤더 노출 제어
+# JWT / AUTH
+ACCESS_TOKEN_SECRET=your_access_token_secret
+REFRESH_TOKEN_SECRET=your_refresh_token_secret
+PASSWORD_PEPPER=your_pepper
 
-### 6) Proxy Trust 설정
+# AWS S3
+AWS_REGION=ap-northeast-2
+AWS_S3_BUCKET_NAME=your_bucket
+AWS_S3_BASE_URL=https://your_bucket.s3.ap-northeast-2.amazonaws.com
+```
 
-- `app.set('trust proxy', [...])`
-  - Nginx 프록시 뒤에서 실행될 때 정확한 IP/프로토콜 정보 사용 가능
+### 2) 패키지 설치
+```bash
+npm install
+```
+
+### 3) 데이터베이스 초기화 (Prisma)
+개발/테스트 환경 모두 Prisma 스키마 기반으로 초기화합니다.
+
+```bash
+npm run prisma:migrate      # 마이그레이션 + 시드 전체 수행
+npm run prisma:generate     # Prisma Client 생성
+npm run prisma:reset        # 개발 DB 초기화
+npm run prisma:studio       # DB UI (웹)
+```
+
+테스트 환경에서 DB 초기화:
+```bash
+npm run test:reset
+npm run test:migrate
+```
 
-### 7) 요청 Body 보호
+### 4) 개발 서버 실행
+백엔드/프론트를 동시에 개발하기 위한 스크립트 포함.
+```bash
+npm run dev        # BE + FE 동시 실행
+npm run dev:be     # 백엔드 단독 실행
+npm run dev:fe     # 프론트 단독 실행
+```
 
-- `express.json({ limit: '2mb' })` 로 본문 크기 제한
-- URL-encoded payload도 제한적 허용
+### 5) 테스트 실행
+테스트 환경(`.env.test`)이 자동 로드되며,  
+테스트용 DB는 매 실행마다 초기화됩니다.
 
-### 8) 쿠키 처리
+```bash
+npm test            # 전체 테스트
+npm run test:watch  # 변경 감지
+npm run test:cov    # 커버리지
+```
 
-- **cookie-parser** 사용
-  - 로그인·세션·보조 데이터 파싱
-  - (필요한 최소 범위로 제한하여 사용)
+### 6) 빌드
+```bash
+npm run build
+```
+빌드 후 결과는 `dist/`에 생성되며 `tsc-alias`로 경로 alias가 자동 변환됩니다.
 
-### 9) 응답 압축
+### 7) 프로덕션 실행
+- **백엔드**: Docker 기반 (EC2)  
+- **프론트엔드**: PM2 기반 Next.js 실행
 
-- **compression(gzip)** 적용
-  - 응답 크기 감소 → DDoS 표면 감소
+```bash
+npm start        # BE + FE
+npm run start:be # 백엔드만
+npm run start:fe # 프론트만
+```
 
-### 10) 정적 파일 보안
+중지:
+```bash
+npm run stop
+```
 
-- MIME 기반 파일 유효성 검사
-- sharp 기반 이미지 처리로 악성 이미지·Payload 숨기기 방지
-- Magic Number 기반 MIME 검증(`assertAllowedByMagic.ts`)
+테스트/운영 DB 혼용을 방지하기 위해  
+`.env.test`에는 운영 DB 정보를 절대 저장하지 않도록 설계되어 있습니다.
 
-### 11) 입력 정화(Input Sanitization)
+## ✨ 주요 구현 하이라이트 (Key Implementations)
 
-- **DOMPurify(isomorphic-dompurify + jsdom)**
-  - 댓글/게시글에서 악성 스크립트 제거 (서버단 Sanitization)
+### 🔹 1) 역할 기반 인증/인가 구조 (RBAC)
+- JWT Access/Refresh Token + DB 기반 Refresh 상태 관리  
+- SUPER_ADMIN / ADMIN / USER 3단 역할을 라우터 단위로 제어  
+- 승인 대기/거절/추가 정보 필요 등 입주민 상태 흐름을 상세하게 모델링
 
-### 12) 인증 보안
+### 🔹 2) 실시간 알림 시스템 (SSE)
+- 민원·공지·투표 등 주요 이벤트 발생 시 즉시 알림 전송  
+- SSE 전역 Emitter 모듈화 → 서비스 레이어에서 단일 API로 사용  
+- 프론트는 알림 Store와 연결되어 실시간 UI 반영
 
-- 로그인/회원가입/토큰 전송은 **JWT Access + Refresh Token 구조**
-- 비밀번호는 **bcrypt + pepper** 조합으로 강화 해싱
-- Refresh Token은 DB에서 상태 관리
-- TokenUtils에서 서명·만료·갱신 로직 통합 관리
+### 🔹 3) Poll 스케줄러 (자동 오픈/마감)
+- Cron 기반 자동 스케줄러 구현  
+- **Limiter(직접 구현)** 로 단일 실행 보장 → 중복 처리/경쟁 조건 제거  
+- 만료 시점에 자동 집계 + 알림까지 일괄 처리
 
-### 13) SSE & WebSocket 보호
+### 🔹 4) 파일 업로드 보안 설계
+- 확장자 기반이 아닌 **Magic Number(MIME)** 검증  
+- `sharp` 재인코딩으로 **폴리글롯(polyglot) 파일 공격** 차단  
+- Presigned URL 방식으로 S3 직접 업로드
 
-- SSE 연결 시 **JWT 기반 헤더 인증**
-- WebSocket(Socket.io)도 미들웨어로 JWT 인증 적용
+### 🔹 5) HTML Sanitization & 입력 검증
+- 서버단 DOMPurify + jsdom으로 XSS 방지  
+- Zod 스키마 기반으로 Params/Query/Body 통합 검증  
+- 검증(Zod) → Sanitize → Controller 흐름으로 전 계층 보호
 
-### 14) 서버 오류 노출 방지
+### 🔹 6) Socket.io 기반 실시간 채팅
+- JWT 인증 미들웨어로 사용자 검증  
+- 관리자 ↔ 입주민 간 빠른 응대 구조 확립  
+- 메시지 저장, 읽음 처리, 채팅방 단위 관리
 
-- 글로벌 에러 핸들러로
-  - 내부 스택트레이스 숨김
-  - 일정한 에러 응답 형식 유지(ApiError)
+### 🔹 7) CSV 기반 입주민 명부 업로드
+- CSV 헤더/타입 정확 검증  
+- 대량 업로드 시 전체를 단일 트랜잭션으로 처리  
+- 잘못된 데이터는 line 단위로 즉시 오류 제공
 
-### 15) Swagger 보안
+### 🔹 8) 테스트 코드 & 안정성
+- 전체 도메인 모듈 통합 테스트 구성 (Jest + Supertest)  
+- 테스트 환경 전용 DB(`setupTestDB`) 자동 초기화  
+- Scheduler·SSE 이벤트까지 독립적으로 검증 가능하도록 구조화
 
-- Swagger 파일이 존재하지 않을 경우 서버 자동 중단  
-  → 잘못 구성된 문서/배포 방지
+### 🔹 9) 안정적인 운영 환경
+- Swagger 미생성 시 서버 부팅 차단  
+- healthcheck 기반 Docker 컨테이너 상태 확인  
+- Nginx + Cloudflare Origin Restore + gzip 압축 조합
 
----
+> 본 프로젝트는 Layered Architecture, 도메인 기반 설계, 테스트·보안·배포 자동화를 모두 갖춘  
+> 실제 운영 수준의 백엔드 아키텍처를 목표로 구현되었습니다.
+> 
+> 또한 모듈 책임 분리, 스프린트 단위 일정 관리, GitHub PR 기반 협업으로  
+> 실제 팀 개발 흐름에 맞춘 운영 프로세스를 유지했습니다.
 
-## ✅ 진행 결과 하이라이트
+## 📎 부록 & 산출물 (Official Project Documents)
 
-- **인프라/배포**
-  - Docker 기반 백엔드 컨테이너 구축 및 Nginx Reverse Proxy 구성
-  - GitHub Actions 기반 CI/CD 파이프라인 구축 (테스트 → 빌드 → GHCR Push → EC2 자동 배포)
-  - RDS/EC2 환경에서 최종 프로덕션 배포 완료 및 안정적 운영 중
+아래 문서는 프로젝트의 전 과정을 정리한 **구글 독스 기반 공식 산출물**입니다.
 
-- **백엔드 아키텍처**
-  - 전체 Prisma 스키마 아키텍처 설계 및 Core 레이어 구축(env/logger/middlewares/router)
-  - Express 5 기반 서버(app.ts) 설계: CSP/보안 헤더, rate-limit, HPP, CORS, Proxy 신뢰, gzip 압축 등 전체 보안 파이프라인 구성
-  - SSE 기반 실시간 알림 시스템 및 Socket.io 실시간 채팅 모듈 구축
-  - Poll 자동 활성화/만료 스케줄러 설계(Limiter 기반 동시성 제어 포함)
+- **1. 요구사항 분석**  
+  https://docs.google.com/document/d/11Kl92rqan2iA_5K8Q_3UCQXxkDiuzfVb10B0d-X-JTQ/edit?usp=sharing
 
-- **백엔드 주요 기능**
-  - 사용자 프로필/이미지 업로드(S3 Presigned URL), 유저 정보 수정 기능
-  - 공지/민원/댓글/입주민/아파트/투표(Polls) CRUD 전체 기능 완성
-  - Notifications REST + SSE 알림 통합 시스템 구현
-  - 이벤트(Calendar) 모듈 구축 및 관리자/유저 권한 흐름 정립
+- **2. 시스템/DB 설계**  
+  https://docs.google.com/document/d/1cymp9U-yK94KXXUE7jiBzh5EP23w9luxXiKN50FrFGA/edit?usp=sharing
 
-- **테스트/품질**
-  - Core, Modules, Jobs 전체에 걸친 통합 테스트 작성(Jest + Supertest)
-  - SSE, Scheduler, Prisma 트랜잭션/캐스케이드 테스트 포함
-  - ESLint/Prettier/tsconfig 구성 정비 및 전체 코드 품질 안정화
+- **3. 구현 문서**  
+  https://docs.google.com/document/d/1hgKMj29_KXsSXFceEgQGOPSlGxUAqYg32ujF5OWZd2U/edit?usp=sharing
 
-- **시연/운영**
-  - Swagger 자동 생성 및 API 문서화 완비
-  - 개발·테스트·프로덕션 환경 분리(.env/.env.test/.env.production)
-  - 프론트엔드 연동 테스트 완료 및 최종 배포 성공
+- **4. 테스트 문서**  
+  https://docs.google.com/document/d/1Dnkksd0Oa1b5dHiuudu5tm-BDBxiOFkTnExfLzwxJVw/edit?usp=sharing
 
----
+- **5. 배포 및 유지보수 문서**  
+  https://docs.google.com/document/d/1Pq4H3DNUBoLCKIp0Jdt3oD8kg3pb66YLEaR4uXr8KJg/edit?usp=sharing
 
-## 📌 링크
-
-- 팀 협업 문서(Notion): 갱신 예정
-- 최종 발표 자료: 갱신 예정
-- 시연 영상: 갱신 예정
-- 저장소: https://github.com/codeit-welive/welive
-- 산출물:
-  - 1. 요구사항 분석: [링크](https://docs.google.com/document/d/11Kl92rqan2iA_5K8Q_3UCQXxkDiuzfVb10B0d-X-JTQ/edit?usp=sharing)
-  - 2. 설계: [링크](https://docs.google.com/document/d/1cymp9U-yK94KXXUE7jiBzh5EP23w9luxXiKN50FrFGA/edit?usp=sharing)
-  - 3. 구현: [링크](https://docs.google.com/document/d/1hgKMj29_KXsSXFceEgQGOPSlGxUAqYg32ujF5OWZd2U/edit?usp=sharing)
-  - 4. 테스트: [링크](https://docs.google.com/document/d/1Dnkksd0Oa1b5dHiuudu5tm-BDBxiOFkTnExfLzwxJVw/edit?usp=sharing)
-  - 5. 배포 및 유지보수: [링크](https://docs.google.com/document/d/1Pq4H3DNUBoLCKIp0Jdt3oD8kg3pb66YLEaR4uXr8KJg/edit?usp=sharing)
+> [!NOTE]  
+> 상단의 “🔗 데모 & 주요 링크”는 실행 가능한 서비스/코드 접근용,  
+> 본 섹션은 프로젝트 진행 전체를 다룬 **정식 문서 산출물 모음**입니다.
diff --git a/docs/assets/erd.png b/docs/assets/erd.png
new file mode 100644
index 0000000..245fcb3
Binary files /dev/null and b/docs/assets/erd.png differ
diff --git a/docs/assets/logo.png b/docs/assets/logo.png
new file mode 100644
index 0000000..cc004b0
Binary files /dev/null and b/docs/assets/logo.png differ
diff --git a/package.json b/package.json
index 5b3c7a2..1651fdf 100644
--- a/package.json
+++ b/package.json
@@ -19,6 +19,8 @@
     "build": "npm run clean && tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json",
     "_section4": "Test",
     "test": "cross-env NODE_ICU_DATA=node_modules/full-icu NODE_ENCODING=utf8 NODE_ENV=test dotenv -e .env.test -- jest --runInBand",
+    "test:watch": "cross-env NODE_ICU_DATA=node_modules/full-icu NODE_ENCODING=utf8 NODE_ENV=test jest --watch",
+    "test:cov": "cross-env NODE_ICU_DATA=node_modules/full-icu NODE_ENCODING=utf8 NODE_ENV=test jest --coverage",
     "test:migrate": "ts-node -r tsconfig-paths/register scripts/test/migrateTestDB.ts",
     "test:reset": "ts-node -r tsconfig-paths/register scripts/test/resetTestDB.ts",
     "_section5": "Development",
diff --git a/src/modules/users/users.service.ts b/src/modules/users/users.service.ts
index c3bc3d6..546efed 100644
--- a/src/modules/users/users.service.ts
+++ b/src/modules/users/users.service.ts
@@ -1,5 +1,6 @@
 import { hashPassword, isPasswordValid } from '#helpers/passwordUtils';
 import ApiError from '#errors/ApiError';
+import env from '#core/env';
 import { findUserById, updateUser } from './users.repo';
 import { USER_MESSAGES as MSG } from '#constants/user.constants';
 import { assertAllowedByMagic } from '#core/files/assertAllowedByMagic';
@@ -53,7 +54,7 @@ export const updateUserService = async (userId: string, { body, file }: UpdateUs
   const updatedUser = await updateUser(userId, updates);
 
   // 기존 아바타 삭제
-  if (updates.avatar && user.avatar) deleteImageFromS3(user.avatar); // fire-and-forget
+  if (updates.avatar && user.avatar !== env.DEFAULT_AVATAR_URL) deleteImageFromS3(user.avatar); // fire-and-forget
 
   return {
     message: `${updatedUser.name}${MSG.UPDATE_SUCCESS}`,