# ghchoi48/heartwings architecture

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

- Interactive diagram: https://gitdiagram.com/ghchoi48/heartwings
- Repository: https://github.com/ghchoi48/heartwings

## Overview

마음나래는 전문상담교사용 로컬 데스크톱 상담 업무 앱입니다. 사용자는 앱을 열고 학교·학생 정보를 준비한 뒤 학생별 상담 기록과 일정을 관리하고 통계·출력으로 결과를 확인합니다. 화면, 저장소, 서비스, SQLCipher 데이터 계층과 외부 연동을 구분했습니다. README가 설명하는 주요 기능은 포함했으며, 일부 하위 모듈은 트리와 문서만 확인되어 그 연결은 생략하거나 미검증으로 표시했습니다.

Main entry points: [`maeumnarae/core/database.py`](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/core/database.py) (암호화 DB), [`maeumnarae/application.py`](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/application.py) (앱 구성), [`maeumnarae/views/students/student_view.py`](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/students/student_view.py) (학생 관리), [`maeumnarae/views/journals/counseling_view.py`](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/journals/counseling_view.py) (상담 일지)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["앱 실행"]
  node_entry["앱 진입<br/>[main.py]"]
  node_application["앱 구성<br/>[application.py]"]
  node_shell["화면 셸<br/>[app_layout.py]"]
end

subgraph group_records["학생과 상담"]
  node_students["학생 관리<br/>[student_view.py]"]
  node_student_store["학생 저장소<br/>[student_repo.py]"]
  node_journals["상담 일지<br/>[counseling_view.py]"]
  node_journal_store["상담 저장소<br/>[counseling_repo.py]"]
  node_journal_types["상담 기록 유형"]
  node_roster["명부 가져오기<br/>[roster_import.py]"]
end

subgraph group_planning["일정과 홈"]
  node_calendar_view["캘린더<br/>[calendar_view.py]"]
  node_calendar_store["일정 저장소<br/>[calendar_repo.py]"]
  node_calendar_services["학사일정 연동"]
  node_google_calendar["구글 캘린더<br/>[google_calendar.py]"]
  node_home["맞춤 홈<br/>[home_repo.py]"]
  node_widgets["홈 위젯"]
end

subgraph group_insights["보고와 데이터 관리"]
  node_reports_view["통계와 출력"]
  node_report_store["통계 저장소<br/>[reporting_repo.py]"]
  node_report_services["통계·PDF 생성"]
  node_data_tools["백업·자료 이관"]
  node_data_views["데이터 설정 화면"]
end

subgraph group_foundation["기반과 연동"]
  node_database[("암호화 DB<br/>[database.py]")]
  node_models["도메인 모델<br/>[models.py]"]
  node_school_services["학교 정보 서비스"]
end

node_user(("상담교사"))
node_internet(("외부 서비스"))

node_user -->|"실행"| node_entry
node_entry -->|"호출"| node_application
node_application -->|"구성"| node_shell
node_application -->|"열기"| node_database
node_shell -.->|"화면 제공"| node_students
node_students -->|"조회·저장"| node_student_store
node_students -->|"학생 일지 열기"| node_journals
node_journals -->|"기록 저장"| node_journal_store
node_journals -->|"학생 조회"| node_student_store
node_journal_types -.->|"유형 저장"| node_journal_store
node_roster -.->|"명부 등록"| node_student_store
node_calendar_view -->|"일정 조회"| node_calendar_store
node_calendar_view -->|"연동 관리"| node_google_calendar
node_calendar_store -->|"읽기·쓰기"| node_database
node_calendar_services -.->|"학사일정 조회"| node_internet
node_google_calendar -.->|"캘린더 연동"| node_internet
node_home -->|"위젯 데이터 저장"| node_database
node_widgets -.->|"정보 표시"| node_school_services
node_widgets -.->|"위젯 상태 사용"| node_home
node_reports_view -.->|"통계 조회"| node_report_store
node_reports_view -->|"보고서·PDF 요청"| node_report_services
node_report_store -->|"집계 조회"| node_database
node_report_store -->|"집계 변환"| node_report_services
node_data_views -->|"백업·복원 요청"| node_data_tools
node_data_tools -->|"검증·복원"| node_database
node_database -->|"모델 참조"| node_models
node_school_services -.->|"외부 조회"| node_internet

click node_entry "https://github.com/ghchoi48/heartwings/blob/main/main.py"
click node_application "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/application.py"
click node_shell "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/shell/app_layout.py"
click node_students "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/students/student_view.py"
click node_student_store "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/students/student_repo.py"
click node_journals "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/journals/counseling_view.py"
click node_journal_store "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/journals/counseling_repo.py"
click node_journal_types "https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/repositories/journals"
click node_roster "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/services/students/roster_import.py"
click node_calendar_view "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/calendar/calendar_view.py"
click node_calendar_store "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/calendar/calendar_repo.py"
click node_calendar_services "https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/calendar"
click node_google_calendar "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/services/calendar/google_calendar.py"
click node_home "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/home/home_repo.py"
click node_widgets "https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/widgets"
click node_reports_view "https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/views/reports"
click node_report_store "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/reports/reporting_repo.py"
click node_report_services "https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/reports"
click node_data_tools "https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/data_management"
click node_data_views "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/settings/database_settings_view.py"
click node_database "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/core/database.py"
click node_models "https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/core/models.py"
click node_school_services "https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/school"

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_entry,node_application,node_shell toneBlue
class node_students,node_student_store,node_journals,node_journal_store,node_journal_types,node_roster toneAmber
class node_calendar_view,node_calendar_store,node_calendar_services,node_google_calendar,node_home,node_widgets toneMint
class node_reports_view,node_report_store,node_report_services,node_data_tools,node_data_views toneRose
class node_database,node_models,node_school_services,node_user,node_internet toneIndigo
```

## Components

### 앱 실행

- [앱 진입](https://github.com/ghchoi48/heartwings/blob/main/main.py): `main.py`
- [앱 구성](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/application.py): `maeumnarae/application.py`
- [화면 셸](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/shell/app_layout.py): `maeumnarae/views/shell/app_layout.py`

### 학생과 상담

- [학생 관리](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/students/student_view.py): `maeumnarae/views/students/student_view.py`
- [학생 저장소](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/students/student_repo.py): `maeumnarae/repositories/students/student_repo.py`
- [상담 일지](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/journals/counseling_view.py): `maeumnarae/views/journals/counseling_view.py`
- [상담 저장소](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/journals/counseling_repo.py): `maeumnarae/repositories/journals/counseling_repo.py`
- [상담 기록 유형](https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/repositories/journals): `maeumnarae/repositories/journals`
- [명부 가져오기](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/services/students/roster_import.py): `maeumnarae/services/students/roster_import.py`

### 일정과 홈

- [캘린더](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/calendar/calendar_view.py): `maeumnarae/views/calendar/calendar_view.py`
- [일정 저장소](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/calendar/calendar_repo.py): `maeumnarae/repositories/calendar/calendar_repo.py`
- [학사일정 연동](https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/calendar): `maeumnarae/services/calendar`
- [구글 캘린더](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/services/calendar/google_calendar.py): `maeumnarae/services/calendar/google_calendar.py`
- [맞춤 홈](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/home/home_repo.py): `maeumnarae/repositories/home/home_repo.py`
- [홈 위젯](https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/widgets): `maeumnarae/widgets`

### 보고와 데이터 관리

- [통계와 출력](https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/views/reports): `maeumnarae/views/reports`
- [통계 저장소](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/repositories/reports/reporting_repo.py): `maeumnarae/repositories/reports/reporting_repo.py`
- [통계·PDF 생성](https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/reports): `maeumnarae/services/reports`
- [백업·자료 이관](https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/data_management): `maeumnarae/services/data_management`
- [데이터 설정 화면](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/views/settings/database_settings_view.py): `maeumnarae/views/settings/database_settings_view.py`

### 기반과 연동

- [암호화 DB](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/core/database.py): `maeumnarae/core/database.py`
- [도메인 모델](https://github.com/ghchoi48/heartwings/blob/main/maeumnarae/core/models.py): `maeumnarae/core/models.py`
- [학교 정보 서비스](https://github.com/ghchoi48/heartwings/tree/main/maeumnarae/services/school): `maeumnarae/services/school`

### Other components

- **상담교사**
- **외부 서비스**

## Connections

- 상담교사 → 앱 진입: 실행 (evidence: `README.md`)
- 앱 진입 → 앱 구성: 호출 (evidence: `main.py`)
- 앱 구성 → 화면 셸: 구성 (evidence: `maeumnarae/application.py`)
- 앱 구성 → 암호화 DB: 열기 (evidence: `maeumnarae/application.py`)
- 화면 셸 → 학생 관리: 화면 제공
- 학생 관리 → 학생 저장소: 조회·저장 (evidence: `maeumnarae/views/students/student_view.py`)
- 학생 관리 → 상담 일지: 학생 일지 열기 (evidence: `maeumnarae/views/students/student_view.py`)
- 상담 일지 → 상담 저장소: 기록 저장 (evidence: `maeumnarae/views/journals/counseling_view.py`)
- 상담 일지 → 학생 저장소: 학생 조회 (evidence: `maeumnarae/views/journals/counseling_view.py`)
- 상담 기록 유형 → 상담 저장소: 유형 저장 (evidence: `maeumnarae/repositories/journals/counseling_repo.py`)
- 명부 가져오기 → 학생 저장소: 명부 등록
- 캘린더 → 일정 저장소: 일정 조회 (evidence: `maeumnarae/views/calendar/calendar_view.py`)
- 캘린더 → 구글 캘린더: 연동 관리 (evidence: `maeumnarae/views/calendar/calendar_view.py`)
- 일정 저장소 → 암호화 DB: 읽기·쓰기 (evidence: `maeumnarae/repositories/calendar/calendar_repo.py`)
- 학사일정 연동 → 외부 서비스: 학사일정 조회 (evidence: `README.md`)
- 구글 캘린더 → 외부 서비스: 캘린더 연동 (evidence: `README.md`)
- 맞춤 홈 → 암호화 DB: 위젯 데이터 저장 (evidence: `maeumnarae/repositories/home/home_repo.py`)
- 홈 위젯 → 학교 정보 서비스: 정보 표시 (evidence: `maeumnarae/widgets/weather.py`)
- 홈 위젯 → 맞춤 홈: 위젯 상태 사용
- 통계와 출력 → 통계 저장소: 통계 조회
- 통계와 출력 → 통계·PDF 생성: 보고서·PDF 요청 (evidence: `maeumnarae/views/reports/journal_print_view.py`)
- 통계 저장소 → 암호화 DB: 집계 조회 (evidence: `maeumnarae/repositories/reports/reporting_repo.py`)
- 통계 저장소 → 통계·PDF 생성: 집계 변환 (evidence: `maeumnarae/repositories/reports/reporting_repo.py`)
- 데이터 설정 화면 → 백업·자료 이관: 백업·복원 요청 (evidence: `maeumnarae/views/settings/database_settings_view.py`)
- 백업·자료 이관 → 암호화 DB: 검증·복원 (evidence: `maeumnarae/services/data_management/database_maintenance.py`)
- 암호화 DB → 도메인 모델: 모델 참조 (evidence: `maeumnarae/core/database.py`)
- 학교 정보 서비스 → 외부 서비스: 외부 조회 (evidence: `README.md`)