# kakaotechcampus-4/ktc4-chungnam-5 architecture

> Architecture diagram of the GitHub repository kakaotechcampus-4/ktc4-chungnam-5, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kakaotechcampus-4/ktc4-chungnam-5
- Repository: https://github.com/kakaotechcampus-4/ktc4-chungnam-5

## Overview

든든지기는 GLP-1 투약자의 끼니 사진을 평가하고 코칭하는 Android 우선 서비스입니다. 사용자는 식사를 등록하고, 백엔드는 비동기 분석을 접수해 워커가 AI 음식 인식을 호출합니다. 사용자가 음식을 확인하면 백엔드는 투약 단계별 기준으로 Q/Q/S 점수를 산출하고 AI가 점수를 문장화합니다. API와 저장·큐 계층, 영양·식사 상태 및 챗봇·안전 기능도 표시했습니다. 관계는 README와 발췌·SOURCE INDEX로 확인되는 것만 연결했습니다. Flutter 화면 소스는 트리에 없어 앱 내부 흐름은 표현하지 않았습니다.

Main entry points: [`ai/app/main.py`](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/main.py) (AI HTTP API), [`backend/app/services/meal.py`](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/services/meal.py) (식사 처리), [`backend/app/db/session.py`](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/db/session.py) (PostgreSQL), [`backend/app/worker/loop.py`](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/worker/loop.py) (워커 루프)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["사용자 앱"]
  node_app["Android 앱 진입<br/>[MainActivity.kt]"]
end

subgraph group_backend["백엔드 API"]
  node_api["공개 API"]
  node_meal_service["식사 처리<br/>[meal.py]"]
  node_qqs["Q/Q/S 규칙 채점"]
  node_other_services["코칭·요약 서비스"]
end

subgraph group_processing["비동기 처리"]
  node_queue["작업 큐<br/>[queue.py]"]
  node_worker["워커 루프<br/>[loop.py]"]
  node_jobs["작업 핸들러"]
  node_ai_client["AI 클라이언트<br/>[ai.py]"]
  node_storage[("사진 저장소<br/>[storage.py]")]
end

subgraph group_ai["AI 서비스"]
  node_ai_api["AI HTTP API<br/>[main.py]"]
  node_food_analysis["음식 인식<br/>[food_analyzer.py]"]
  node_short_feedback["짧은 피드백<br/>[short_feedback.py]"]
  node_coach["대화 코치<br/>[ai_coach.py]"]
  node_safety["안전 검사<br/>[safety_guard.py]"]
  node_ai_contract["AI 계약 스키마<br/>[schemas.py]"]
end

subgraph group_domain["도메인 데이터"]
  node_database[("PostgreSQL<br/>[session.py]")]
  node_meal_data[("식사·음식 데이터<br/>[meal.py]")]
  node_feedback_data[("피드백 데이터<br/>[feedback.py]")]
  node_medication_data[("투약 데이터<br/>[medication.py]")]
end

node_user(("식사 사용자"))

node_user -.->|"등록·조회"| node_app
node_app -.->|"API 요청"| node_api
node_api -.->|"호출"| node_meal_service
node_meal_service -->|"작업 등록"| node_queue
node_meal_service -->|"사진 저장"| node_storage
node_worker -->|"작업 가져오기"| node_queue
node_worker -.->|"작업 전달"| node_jobs
node_worker -->|"AI 호출"| node_ai_client
node_ai_client -->|"HTTP 요청"| node_ai_api
node_ai_api -->|"호출"| node_food_analysis
node_ai_api -->|"호출"| node_short_feedback
node_ai_api -->|"호출"| node_coach
node_ai_api -->|"검사"| node_safety
node_ai_api -->|"검증"| node_ai_contract
node_meal_service -.->|"채점 요청"| node_qqs
node_meal_service -->|"세션 사용"| node_database
node_database -.->|"영속화"| node_meal_data
node_database -.->|"영속화"| node_feedback_data
node_database -.->|"영속화"| node_medication_data
node_other_services -.->|"세션 사용"| node_database

click node_app "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/frontend/android/app/src/main/kotlin/com/ktc4/chungnam5/frontend/MainActivity.kt"
click node_api "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/api/v1/endpoints"
click node_meal_service "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/services/meal.py"
click node_qqs "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/services/evaluation"
click node_other_services "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/services"
click node_queue "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/infra/queue.py"
click node_worker "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/worker/loop.py"
click node_jobs "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/worker/jobs"
click node_ai_client "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/infra/ai.py"
click node_storage "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/infra/storage.py"
click node_ai_api "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/main.py"
click node_food_analysis "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/food_analyzer.py"
click node_short_feedback "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/short_feedback.py"
click node_coach "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/ai_coach.py"
click node_safety "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/safety_guard.py"
click node_database "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/db/session.py"
click node_meal_data "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/models/meal.py"
click node_feedback_data "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/models/feedback.py"
click node_medication_data "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/models/medication.py"
click node_ai_contract "https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/schemas.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app toneBlue
class node_api,node_meal_service,node_qqs,node_other_services toneAmber
class node_queue,node_worker,node_jobs,node_ai_client,node_storage toneMint
class node_ai_api,node_food_analysis,node_short_feedback,node_coach,node_safety,node_ai_contract toneRose
class node_database,node_meal_data,node_feedback_data,node_medication_data,node_user toneIndigo
```

## Components

### 사용자 앱

- [Android 앱 진입](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/frontend/android/app/src/main/kotlin/com/ktc4/chungnam5/frontend/MainActivity.kt): `frontend/android/app/src/main/kotlin/com/ktc4/chungnam5/frontend/MainActivity.kt`

### 백엔드 API

- [공개 API](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/api/v1/endpoints): `backend/app/api/v1/endpoints`
- [식사 처리](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/services/meal.py): `backend/app/services/meal.py`
- [Q/Q/S 규칙 채점](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/services/evaluation): `backend/app/services/evaluation`
- [코칭·요약 서비스](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/services): `backend/app/services`

### 비동기 처리

- [작업 큐](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/infra/queue.py): `backend/app/infra/queue.py`
- [워커 루프](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/worker/loop.py): `backend/app/worker/loop.py`
- [작업 핸들러](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/tree/develop/backend/app/worker/jobs): `backend/app/worker/jobs`
- [AI 클라이언트](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/infra/ai.py): `backend/app/infra/ai.py`
- [사진 저장소](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/infra/storage.py): `backend/app/infra/storage.py`

### AI 서비스

- [AI HTTP API](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/main.py): `ai/app/main.py`
- [음식 인식](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/food_analyzer.py): `ai/app/food_analyzer.py`
- [짧은 피드백](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/short_feedback.py): `ai/app/short_feedback.py`
- [대화 코치](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/ai_coach.py): `ai/app/ai_coach.py`
- [안전 검사](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/safety_guard.py): `ai/app/safety_guard.py`
- [AI 계약 스키마](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/ai/app/schemas.py): `ai/app/schemas.py`

### 도메인 데이터

- [PostgreSQL](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/db/session.py): `backend/app/db/session.py`
- [식사·음식 데이터](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/models/meal.py): `backend/app/models/meal.py`
- [피드백 데이터](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/models/feedback.py): `backend/app/models/feedback.py`
- [투약 데이터](https://github.com/kakaotechcampus-4/ktc4-chungnam-5/blob/develop/backend/app/models/medication.py): `backend/app/models/medication.py`

### Other components

- **식사 사용자**

## Connections

- 식사 사용자 → Android 앱 진입: 등록·조회
- Android 앱 진입 → 공개 API: API 요청
- 공개 API → 식사 처리: 호출
- 식사 처리 → 작업 큐: 작업 등록 (evidence: `backend/app/services/meal.py`)
- 식사 처리 → 사진 저장소: 사진 저장 (evidence: `backend/app/services/meal.py`)
- 워커 루프 → 작업 큐: 작업 가져오기 (evidence: `backend/app/worker/loop.py`)
- 워커 루프 → 작업 핸들러: 작업 전달
- 워커 루프 → AI 클라이언트: AI 호출 (evidence: `backend/app/worker/loop.py`)
- AI 클라이언트 → AI HTTP API: HTTP 요청
- AI HTTP API → 음식 인식: 호출 (evidence: `ai/app/main.py`)
- AI HTTP API → 짧은 피드백: 호출 (evidence: `ai/app/main.py`)
- AI HTTP API → 대화 코치: 호출 (evidence: `ai/app/main.py`)
- AI HTTP API → 안전 검사: 검사 (evidence: `ai/app/main.py`)
- AI HTTP API → AI 계약 스키마: 검증 (evidence: `ai/app/main.py`)
- 식사 처리 → Q/Q/S 규칙 채점: 채점 요청
- 식사 처리 → PostgreSQL: 세션 사용 (evidence: `backend/app/services/meal.py`)
- PostgreSQL → 식사·음식 데이터: 영속화
- PostgreSQL → 피드백 데이터: 영속화
- PostgreSQL → 투약 데이터: 영속화
- 코칭·요약 서비스 → PostgreSQL: 세션 사용
