하드웨어 배선도 추가 및 하드웨어, 백엔드 내용 보충

Author: kth0910

assets/images/하드웨어배선도.png

@@ -10,15 +10,75 @@ permalink: /documents/developments/backend/
 
 # 🔧 백엔드 개발 가이드
 
-## 서버 구조
-- FastAPI 기반 REST API 서버  
-- [API 명세서 보러 가기](api-reference.md)
+살가이 프로젝트의 백엔드 서버는 **FastAPI 프레임워크**를 기반으로 구축되었으며, 라즈베리파이, LLM 서버, 프론트엔드 애플리케이션과의 안정적인 통신을 담당합니다. 사용자 등록, 복약 기록 저장, 스케줄 기반 알림 제어, 음성 텍스트 전달 등 다양한 기능을 API 단위로 처리하며, 모든 처리는 경량화된 구조 내에서 실시간으로 수행됩니다.
 
-## 주요 워크플로우
+---
+
+## ✅ 서버 아키텍처
+
+- **프레임워크**: FastAPI  
+- **배포 환경**: AWS EC2 (Ubuntu 22.04 LTS 기준)  
+- **프로세스 관리**: Node.js 기반의 PM2 활용  
+- **데이터베이스**: SQLite (테스트용, 향후 PostgreSQL 확장 가능)
+
+API 서버는 `/api`로 시작되는 RESTful 라우팅 구조를 따르며, 주요 기능별로 라우터가 분리되어 있습니다.
+
+---
+
+## 🔁 배포 및 자동화 워크플로우
+
+- **GitHub Actions** 또는 수동 방식 모두 지원
+- `main` 브랜치로 코드가 push되면, EC2 서버에서 자동으로 `git pull` → `pm2 restart` 순서로 실행
+- `deploy-cicd.yml` 스크립트로 다음을 수행:
+  1. 저장소 pull
+  2. 변경된 의존성 설치
+  3. 서버 프로세스 재시작 (pm2 기반)
+
+---
+
+## 🚀 실행 방식
+
+### 1. FastAPI 서버 실행
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 8000
+#또는
+```
+
+> 배포 환경에서는 `pm2`로 실행하며 백그라운드 유지 및 자동 재시작을 보장합니다.
 
-- main 브랜치에 코드 push 시 EC2 서버에 자동 배포 스크립트 실행
+### 2. PM2 관리
+
+```bash
+pm2 start "python main.py" --name main
+pm2 restart main
+pm2 logs main
+```
+
+- 로그 파일 위치: `~/.pm2/logs/main-out.log`
+- 에러 로그: `~/.pm2/logs/main-error.log`
+
+---
+
+## 🔐 인증 및 사용자 관리
+
+- 관리자, 보호자, 일반 사용자로 구분된 인증 구조는 추후 OAuth 또는 JWT 기반으로 확장 예정
+- 현재는 로그인 시에만 토큰 기반 검증 로직을 사용 중 (개발 편의 목적)
+
+
+---
+
+## 📌 유지보수 전략
+
+- EC2 서버는 `ufw` 방화벽으로 포트를 제한하고, API 서버는 `8000` 포트만 외부에 공개
+- SSH 접속은 공개키 기반 인증 사용
+- 추후에는 `Nginx` 리버스 프록시 설정 및 HTTPS 적용 예정
+
+---
 
-## 실행 방식
-- PM2를 통한 지속 실행
-- 로그는 `~/.pm2/logs/`에서 확인 가능
+## 🔚 마무리
 
+살가이 백엔드 서버는 다양한 디바이스와의 연동을 전제로 설계된 **경량화되고 유연한 REST API 시스템**입니다.  
+FastAPI 기반 구조는 비동기 처리와 모듈 확장에 강점을 가지며, EC2와 PM2를 통해 높은 안정성과 운영 효율성을 확보하고 있습니다.  
+AI 추론, 음성 데이터 수집, 복약 스케줄 관리 등 다양한 기능이 하나의 백엔드 시스템으로 통합되어 있으며, 추후 사용자 인증/보안 강화, 데이터 시각화 기능도 지속 확장될 예정입니다.
+```

documents/development/api-reference.md

@@ -9,11 +9,81 @@ permalink: /documents/developments/hardware/
 
 # 🧩 하드웨어 구성
 
+![하드웨어 배선도](/assets/images/하드웨어배선도.png)
+
+살가이 프로젝트의 하드웨어는 **라즈베리파이 5**를 기반으로 한 단일 디바이스로, 고령의 사용자가 직접 대면하게 되는 **AI 스피커 형태의 인터페이스**입니다.  
+이 장치는 음성 기반 복약 확인 시스템의 물리적 인터페이스를 구성하며, 추상화를 위해 상호작용 중심의 기능을 **온전히 서버에서 처리**하도록 설계되어 있습니다.
+
+---
+
 ## 사용된 장비
-- **라즈베리파이 5**
-- **스피커 (3.5mm 또는 USB)**
-- **마이크 (헤드셋 또는 외장형)**
-- **LED (상태 시각화: 대기/녹음/에러)**
-- **디스플레이 (복약 시간 안내 및 피드백 시각화)**
 
-라즈베리파이는 복약 시간에 따라 알림을 출력하고, 사용자의 음성 응답을 녹음하여 서버로 전송하는 기능을 담당합니다.
+- **🧠 라즈베리파이 5**  
+  전체 하드웨어 제어 및 음성 인터페이스 실행. 복약 알림, 녹음, 음성 피드백, 등을 모두 담당합니다.
+
+- **🔊 스피커**  
+  서버로부터 받은 TTS 음성 파일을 재생하여 사용자에게 피드백을 제공합니다.
+
+- **🎤 마이크**  
+  사용자의 음성을 녹음하여 STT 처리를 위한 WAV 파일을 생성합니다. Wake Word 감지 루틴과 복약 응답 루틴에서 모두 활용됩니다.
+
+- **🔴 LED (상태 시각화용)**  
+  복약 루틴 또는 음성 처리 과정의 상태를 사용자에게 시각적으로 전달하기 위해 컬러 LED를 사용합니다.
+  
+  | 상태 | 색상 | 의미 |
+  |------|------|------|
+  | 대기 | OFF | 아무 동작 없음 |
+  | 녹음/출력 | 파랑(B) | 음성 입출력 중 |
+  | 판단 중 | 초록(G) | AI 분석 진행 중 |
+  | 오류 | 빨강(R) | 처리 중 오류 발생 |
+
+- **🖥 디스플레이**  
+  복약 알림, 현재 시각, 피드백 메시지 등을 표시하는 시각적 출력 장치로, UI는 키오스크 형태로 구성됩니다. 스피커의 UI는 React 기반의 웹 페이지로 구현되어 라즈베리파이에 연결할 필요 없이 외부 디스플레이를 사용하는 것도 가능합니다.  
+
+- **🔘 버튼 (선택적)**  
+  음성 인터페이스 사용이 어려운 경우를 대비하여 물리적 버튼으로 알림 확인이나 녹음 종료 트리거를 줄 수 있습니다.
+
+---
+
+## 하드웨어 구성의 핵심 원칙
+
+1. **고령자 사용성 중심 설계**  
+   - 버튼, 음성, LED, 화면 등 다양한 피드백 채널을 활용해 사용자의 이해를 돕습니다.
+   - 음성 인식 실패나 무응답 상황에 대비해 **시각적 피드백과 물리 버튼**을 병행 지원합니다.
+
+2. **로컬에서 경량 동작**  
+   - STT, TTS, LLM 처리는 서버에서 담당하고, 라즈베리파이는 오직 녹음, 전송, 재생 루틴만 처리합니다.
+   - 복잡한 연산을 서버로 위임함으로써 하드웨어 부담을 최소화하고 발열·속도 문제를 방지합니다.
+
+
+---
+
+## Wake Word 감지
+
+- Wake Word는 `pvporcupine` 라이브러리를 사용하여 "살가이"라는 음성을 로컬에서 실시간 감지합니다.
+- 이를 통해 사용자는 버튼 없이도 음성으로 장치를 깨우고 대화를 시작할 수 있습니다.
+
+---
+
+## 마이크 충돌 해결
+
+- Wake Word 루틴과 녹음 루틴은 서로 다른 쓰레드로 실행되며, **ALSA 장치 사용 충돌을 방지하기 위해 `mic_lock`**을 구현했습니다.
+- Wake Word 감지 루틴은 잠시 마이크 점유를 해제하고, 녹음이 끝난 뒤 재시작됩니다.
+
+---
+
+## 💡 사용성 예시
+
+- **복약 전**  
+  🔈 "살가이, 지금 몇 시야?"  
+  📺 디스플레이: `지금은 오전 8시 57분입니다.`
+
+- **복약 시간 도달 시**  
+  🔔 알림: "아침 약 드실 시간이에요. 식사하셨나요?"  
+  🔴 LED: 파랑 → 초록  
+  📤 녹음 후 전송
+
+- **결과 피드백**  
+  🔈 "식사 맛있게 하셨으니 이제 약 드실 시간이에요! 얼른 드시고 말씀해 주세요."
+
+---

documents/development/backend.md

@@ -76,8 +76,6 @@ permalink: /documents/developments/
 - **데이터베이스**: 현재는 SQLite 사용 (가볍고 관리 용이).  
   향후 안정성과 확장성을 고려해 PostgreSQL 이관을 검토 중입니다.
 
-### [📘 API 명세서 보기](APIspecification)
-
 ---
 
 ## [🎨 3. 프론트엔드 (React + Vite + TailwindCSS)](frontend)