tst-claude-code-samples/technical_blueprint.md

# AIROUM 프로젝트 기술 청사진 (Technical Blueprint) v1.0

## 1. 프로젝트 개요 (Project Overview)

AIROUM 프로젝트의 핵심 목표는 'AI와 새로움'의 가치를 효과적으로 전달하고, 잠재 고객이 AI 교육 프로그램을 쉽게 이해하여 문의 및 신청으로 이어지게 하는 공식 랜딩 페이지를 제작하는 것입니다. 최종 결과물은 빠른 로딩 속도와 명확한 사용자 경험을 제공하며, '문의하기'라는 핵심 기능에 집중한 경량의 웹 애플리케이션입니다.

주요 기술 스택은 **프론트엔드에 순수 HTML, CSS, 최소한의 Vanilla JavaScript**를, **백엔드에는 Python 기반의 Flask 마이크로 프레임워크**를, **데이터베이스는 SQLite**를 사용합니다. 이 스택은 빠른 개발 속도, 쉬운 유지보수, 낮은 서버 복잡성을 목표로 선정되었으며, 특히 '문의하기'라는 단일 동적 기능을 안정적으로 처리하는 데 최적화되어 있습니다.

## 2. 상세 프로젝트 구조 (Detailed Project Structure)

### **프론트엔드 디렉토리 구조**

React나 Vue 같은 프레임워크를 사용하지 않으므로, `static` 폴더를 중심으로 단순하고 직관적인 구조를 유지합니다.

```
/airoum-landing
├── app.py                 # Flask 애플리케이션
├── requirements.txt       # Python 의존성
├── templates/
│   └── index.html         # 메인 랜딩 페이지 HTML
└── static/
    ├── css/
    │   └── style.css      # 메인 스타일시트
    ├── js/
    │   ├── main.js        # 공통 스크립트 (e.g., 네비게이션)
    │   └── form.js        # 문의하기 폼 전용 스크립트
    └── images/
        ├── logo.svg
        └── hero-background.mp4
```

*   `static/css/style.css`: 모든 페이지의 스타일을 정의합니다. BEM(Block, Element, Modifier) 방법론을 적용하여 클래스명을 구조화합니다.
    ```css
    /* 예시: BEM 적용 */
    .btn { /* ... */ }
    .btn--primary { /* ... */ }
    .form__input { /* ... */ }
    .form__input--error { /* ... */ }
    ```
*   `static/js/form.js`: '문의 및 신청' 폼의 유효성 검사 및 AJAX를 통한 API 서버 통신을 담당합니다.
    ```javascript
    // 예시: 문의 폼 제출 로직
    document.getElementById('inquiry-form').addEventListener('submit', async (e) => {
      e.preventDefault();
      const formData = new FormData(e.target);
      const data = Object.fromEntries(formData.entries());

      try {
        const response = await fetch('/api/inquiry', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify(data),
        });
        // ... 성공/실패 처리
      } catch (error) {
        // ... 네트워크 에러 처리
      }
    });
    ```

### **백엔드 아키텍처**

기술 설계서에 명시된 대로, 단일 책임을 갖는 최소주의 아키텍처를 따릅니다. 복잡한 서비스 레이어 없이, `app.py` 내에서 라우트 핸들러가 직접 요청을 처리하고 데이터베이스와 상호작용하는 단순한 구조를 채택합니다.

*   **API 라우팅**: `app.py` 파일에 모든 라우트를 정의합니다.
    *   `@app.route('/')`: 메인 랜딩 페이지(`index.html`)를 렌더링합니다.
    *   `@app.route('/api/inquiry', methods=['POST'])`: 문의 데이터를 받아 처리하는 유일한 API 엔드포인트입니다.
*   **데이터베이스 상호작용**: Flask 라우트 핸들러 내에서 직접 SQLite 데이터베이스 커넥션을 열고, `INSERT` 쿼리를 실행하여 문의 내용을 저장합니다.

### **데이터베이스 스키마**

시스템의 유일한 테이블인 `INQUIRIES`만 존재합니다.

| 컬럼명 | 데이터 타입 | 제약 조건 | 설명 |
| :--- | :--- | :--- | :--- |
| `id` | `INTEGER` | `PRIMARY KEY AUTOINCREMENT` | 고유 식별자 |
| `name` | `VARCHAR(50)` | `NOT NULL` | 문의자 이름 |
| `email` | `VARCHAR(100)` | `NOT NULL` | 문의자 이메일 |
| `phone` | `VARCHAR(20)` | `NULL` | 문의자 연락처 (선택) |
| `message` | `TEXT` | `NOT NULL` | 문의 내용 |
| `created_at` | `DATETIME` | `NOT NULL, DEFAULT CURRENT_TIMESTAMP` | 문의 접수 일시 |

## 3. 핵심 개발 방향 및 로드맵 (Core Development Direction & Roadmap)

### **개발 1단계 (Phase 1 - MVP)**

가장 먼저 구현해야 할 핵심 기능은 다음과 같습니다.

1.  **[P1] 회사 및 교육 프로그램 소개 페이지 구현**: `aroum_landing_page_plan.md`에 기획된 Hero, About, Core Programs 섹션을 포함한 정적 페이지를 HTML/CSS로 완성합니다.
2.  **[P2] 문의하기 기능 구현 (End-to-End)**: 프론트엔드의 '문의 및 신청' 폼 UI를 만들고, 백엔드의 `POST /api/inquiry` 엔드포인트와 연동하여 실제 데이터가 SQLite DB에 저장되는 흐름을 완성합니다.
3.  **[P3] 반응형 디자인 적용**: 모바일, 태블릿, 데스크탑 환경에서 깨짐 없이 콘텐츠가 표시되도록 CSS 미디어 쿼리를 적용합니다.

### **기술적 원칙 (Technical Principles)**

*   **코딩 컨벤션**:
    *   Python: [PEP 8](https://www.python.org/dev/peps/pep-0008/) 스타일 가이드를 준수합니다.
    *   CSS: BEM 방법론을 사용하여 클래스명을 작성하고, `prettier`를 통해 코드 스타일을 통일합니다.
    *   JavaScript: `ESLint`와 `prettier`를 사용하여 코드 품질과 일관성을 유지합니다.
*   **상태 관리**: 클라이언트 측 상태 관리는 최소화합니다. 모든 상태는 서버로부터 받거나, 폼 입력과 같이 일시적인 UI 상태만 Vanilla JS로 관리합니다.
*   **테스트 정책**: MVP 단계에서는 단위 테스트보다 핵심 기능(문의 제출)에 대한 수동 E2E(End-to-End) 테스트에 집중합니다.
*   **API 설계 원칙**: `technical-design-document.md`에 정의된 단일 엔드포인트 명세를 엄격히 따릅니다. 요청/응답 형식은 JSON으로 통일하고, 성공/실패 상태를 명확히 반환합니다.

### **주요 컴포넌트 설계**

향후 TypeScript 기반 프레임워크로의 확장을 고려하여 주요 컴포넌트의 인터페이스를 정의합니다. 실제 구현은 CSS 클래스와 HTML 구조로 진행합니다.

*   **Button (`.btn`)**
    ```typescript
    interface ButtonProps {
      label: string;
      variant?: 'primary' | 'secondary';
      onClick: () => void;
      disabled?: boolean;
    }
    ```
*   **Modal (`.modal`)**
    ```typescript
    interface ModalProps {
      isOpen: boolean;
      onClose: () => void;
      title: string;
      children: React.ReactNode; // 실제로는 HTML 콘텐츠가 들어감
    }
    ```
*   **Input (`.form__input`)**
    ```typescript
    interface InputProps {
      id: string;
      label: string;
      value: string;
      onChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
      placeholder?: string;
      error?: string;
    }
    ```

## 4. 즉시 실행할 액션 아이템 (Immediate Action Items)

개발팀은 다음 주까지 아래 작업을 완료해야 합니다.

1.  **GitHub 레포지토리 생성 및 초기 설정**: `airoum-landing` 레포지토리를 생성하고, `main` 브랜치 보호 규칙을 설정합니다. 위에서 정의한 디렉토리 구조와 `requirements.txt`, `.gitignore` 파일을 포함한 초기 커밋을 완료합니다.
2.  **Flask 기본 환경 설정 및 'Hello World' 배포**: `app.py`에 기본 Flask 앱을 설정하고, `/` 경로에서 `index.html`을 렌더링하는 기능을 구현합니다. 이를 Gunicorn을 통해 로컬 환경에서 실행하는 것을 확인합니다.
3.  **랜딩 페이지 Hero 섹션 마크업 및 스타일링 착수**: `aroum_landing_page_plan.md` 기획안에 따라, 동영상 배경을 포함한 Hero 섹션의 HTML 구조와 기본 CSS 스타일링 작업을 시작합니다.