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) 방법론을 적용하여 클래스명을 구조화합니다.

  /* 예시: BEM 적용 */
  .btn { /* ... */ }
  .btn--primary { /* ... */ }
  .form__input { /* ... */ }
  .form__input--error { /* ... */ }
  

• static/js/form.js: '문의 및 신청' 폼의 유효성 검사 및 AJAX를 통한 API 서버 통신을 담당합니다.

  // 예시: 문의 폼 제출 로직
  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 스타일 가이드를 준수합니다.
  • 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)

  interface ButtonProps {
    label: string;
    variant?: 'primary' | 'secondary';
    onClick: () => void;
    disabled?: boolean;
  }
  

• Modal (.modal)

  interface ModalProps {
    isOpen: boolean;
    onClose: () => void;
    title: string;
    children: React.ReactNode; // 실제로는 HTML 콘텐츠가 들어감
  }
  

• Input (.form__input)

  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 스타일링 작업을 시작합니다.