---
document_type: architecture
priority: HIGH
---
# 프로젝트 구조 및 아키텍처 명세

## 1. 아키텍처 기본 원칙
* **수직 통합:** 백엔드 로직과 프론트엔드 코드는 페이지 폴더(`A01_`, `B01_` 등)별로 격리. 거대 단일 모듈을 금지하고 기능별로 파일을 분할한다.
* **루트 main.py:** FastAPI 진입점으로, 라우터 등록(`include_router`)만 수행. 비즈니스 로직 작성 금지.
* **명명 규칙:** 
  - 백엔드: `[폴더명]_Router.py`, `[폴더명]_Engine.py`, `[폴더명]_Schema.py`, `[폴더명]_Repository.py`
  - 프론트엔드: `[폴더명]_UI_Page.ts`, `[폴더명]_UI_Style.css`, `[폴더명]_Api_Fetch.ts`
  - 로그인 전은 `A01_`, 로그인 후는 `B01_`, 워크플로우는 `B04_wf1_` 형태 적용.
  - 공통 유틸 코드는 `common_util_[기능].확장자`

## 2. 전체 디렉토리 트리 상세

```text
my-project/
├── A00_Common/                      # 프론트엔드 공통 인프라
│   ├── main.ts                     # 앱 진입점
│   ├── router.ts                   # 해시 기반 SPA 라우터
│   └── app_shell.ts                # 공통 헤더/푸터
├── common_util/                     # 공통 유틸리티
│   ├── common_util_validate.ts     # 프론트 유효성 검사
│   ├── common_util_storage.py      # 저장 경로 로직
│   └── common_util_workflow.py     # 상태 동기화 로직
├── config/                          # 환경 설정
│   ├── config_system.py             # 시스템 파라미터 (제어 변수 중앙화)
│   └── config_db.py                 # DB 설정
├── db_management/                   # 스키마 및 마이그레이션
├── resources/                       # 정적 리소스 (에셋)
├── storage/                         # 물리 파일 영구 저장소 (DB와 매핑)
├── templates/                       # 보고서/도면 양식
├── ui_template/                     # 공통 UI 컴포넌트, 테마, 다국어
│   ├── ui_template_theme.css       
│   ├── ui_template_locale.ts       
│   └── ui_template_elements.ts     

# --- 로그인 전 페이지 (A 그룹) ---
├── A01_Home/                        # 홈 (소개, 소식)
├── A02_ProgDetail/                  # 프로그램 상세 (6단계 워크플로우 설명)
├── A03_CompDetail/                  # 회사 상세 (미션 등)
├── A04_NewsHistory/                 # 최신소식 및 개선 이력
├── A05_EduDetail/                   # 교육 상세
├── A06_Login/                       # 로그인 (이메일/비밀번호)
├── A07_Register/                    # 회원가입
├── A08_Support/                     # 기술지원 요청

# --- 로그인 후 페이지 (B 그룹) ---
├── B01_AccountDetail/               # 계정 관리
├── B02_ProjRegister/                # 신규 프로젝트 등록
├── B03_FileInput/                   # [WF0] 원본 파일 입력 (다중 파일 업로드)
├── B04_wf1_Surface/                 # [WF1] 지표면 모델 분석 (LAS 처리)
├── B05_wf2_Route/                   # [WF2] 경로 설계 (최적 경로 계산)
├── B06_wf3_ProfileCross/            # [WF3] 종횡단 생성 (단면 추출)
├── B07_wf4_DesignDetail/            # [WF4] 상세 설계 (구조물 배치)
├── B08_wf5_Quantity/                # [WF5] 수량 산출 (물량 집계)
├── B09_wf6_Estimation/              # [WF6] 견적/최종 산출물 생성
├── B10_Payment/                     # 결제 관리
└── B11_Status/                      # 상태 출력 페이지

├── main.py                          # FastAPI 루트
└── package.json, requirements.txt 등
```