tst-claude-code-samples/.taskmaster/docs/technical-design-document.md

AIROUM 랜딩 페이지 기술 설계서 (v2.0 - Minimalist)

1. 프로젝트 목표 및 핵심 원칙

본 문서는 AIROUM 랜딩 페이지의 기술 설계를 정의합니다. v2.0 설계의 핵심 목표는 '문의하기'라는 단 하나의 기능에 집중하여, 가장 빠르고 안정적으로 사용자의 문의를 접수하는 것입니다. 모든 부가 기능(회원가입, 관리자 페이지 등)은 의도적으로 배제하여 복잡성을 최소화합니다.

• 단일 책임 원칙 (Single Responsibility): 이 시스템의 유일한 책임은 '문의 데이터 수신 및 저장'입니다.
• 최소주의 아키텍처 (Minimalist Architecture): 가장 필수적인 기술 요소만 사용하여 가볍고 빠른 시스템을 구축합니다.
• 사용자 경험 최우선 (UX First): 기능이 단순한 만큼, 사용자의 첫인상을 결정하는 랜딩 페이지의 UI/UX와 성능을 최우선으로 고려합니다.

2. 시스템 아키텍처 (Simplified Architecture)

2.1. 아키텍처 다이어그램

graph TD
    subgraph "사용자"
        A[사용자 브라우저]
    end

    subgraph "인프라 (자체 서버)"
        B[Nginx] --> D{Flask App}
        D --> E[SQLite DB]
    end

    A -- "Page Request" --> B
    B -- "Static Files" --> A
    B -- "Proxy API Request" --> D
    A -- "Submit Inquiry" --> D
    D -- "Save Data" --> E

    style A fill:#f9f,stroke:#333,stroke-width:2px
    style B fill:#ccf,stroke:#333,stroke-width:2px
    style D fill:#cfc,stroke:#333,stroke-width:2px
    style E fill:#fcf,stroke:#333,stroke-width:2px

2.2. 아키텍처 설명

• Nginx (웹 서버): 모든 외부 요청의 진입점입니다. HTML, CSS, JavaScript, 이미지와 같은 정적 파일은 Nginx가 직접 처리하여 최고의 속도를 보장합니다. API 요청(POST /api/inquiry)만 Flask 애플리케이션으로 전달합니다.
• Flask App (백엔드): 오직 하나의 역할, 즉 POST /api/inquiry 요청을 받아 유효성을 검사하고 데이터베이스에 저장하는 역할만 수행합니다.
• SQLite (데이터베이스): 문의 내용을 저장하기 위한 단일 파일 기반 데이터베이스입니다. 별도의 설정이 필요 없어 배포가 매우 간단하며, 소규모 데이터 처리에 적합합니다.

3. 데이터베이스 설계 (Single Table Design)

시스템의 유일한 데이터 모델은 '문의(Inquiry)'입니다.

3.1. INQUIRIES 테이블 스키마

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

선택 이유: USERS, COURSES 등 모든 부가 테이블을 제거하고 INQUIRIES 테이블만 남겨 데이터 모델을 극도로 단순화했습니다. 이는 시스템의 복잡성을 줄이고 유지보수 비용을 최소화합니다.

4. API 명세 (Single Endpoint Specification)

시스템에는 단 하나의 API 엔드포인트만 존재합니다.

문의 등록 API

• Endpoint: POST /api/inquiry
• Description: 사용자의 문의를 시스템에 등록합니다.
• Request Body (JSON):

  {
    "name": "김에이",
    "email": "airoum.kim@example.com",
    "phone": "010-1234-5678",
    "message": "AI 윤리 교육에 대해 더 자세히 알고 싶습니다."
  }
  

• Success Response (201 Created):

  {
    "status": "success",
    "message": "문의가 성공적으로 접수되었습니다."
  }
  

• Error Response (400 Bad Request):

  {
    "status": "error",
    "message": "입력값을 확인해주세요.",
    "errors": {
      "email": "올바른 이메일 형식이 아닙니다."
    }
  }
  

5. 프론트엔드 구현 전략 (UI/UX & Performance Focus)

기능이 최소화된 만큼, 랜딩 페이지 자체의 완성도가 프로젝트의 성패를 좌우합니다.

5.1. 핵심 목표

• 빠른 로딩 속도: 사용자가 페이지를 이탈하지 않도록 2초 이내에 주요 콘텐츠가 렌더링되는 것을 목표로 합니다.
• 명확한 CTA (Call to Action): 사용자가 '문의하기' 버튼을 쉽게 찾고 클릭할 수 있도록 디자인합니다.
• 직관적인 UI/UX: 불필요한 정보를 제거하고, AIROUM의 핵심 가치와 교육 프로그램을 명확하게 전달합니다.

5.2. 성능 최적화 전략

• 이미지 최적화: 모든 이미지는 WebP 포맷으로 변환하고, lazy loading을 적용하여 초기 로딩 속도를 개선합니다.
• CSS/JS 최소화: 순수 CSS와 최소한의 Vanilla JS를 사용합니다. CSS는 Critical CSS를 인라인으로 삽입하고, 나머지는 비동기적으로 로드합니다. JavaScript는 defer 속성을 사용하여 HTML 파싱을 방해하지 않도록 합니다.
• 브라우저 캐싱 활용: Nginx 설정을 통해 정적 파일에 대해 긴 만료 시간(long expiry dates)을 설정하여 반복 방문 시 로딩 속도를 높입니다.

5.3. '문의하기' 폼 UX 전략

• 입력 필드 최소화: 이름, 이메일, 연락처(선택), 문의 내용 필드를 배치하여 사용자 피로도를 줄입니다.
• 실시간 유효성 검사: 이메일 형식 등을 실시간으로 검사하여 사용자에게 즉각적인 피드백을 제공합니다.
• 명확한 피드백: '제출' 버튼 클릭 시, 로딩 상태를 명확히 보여주고, 성공 또는 실패 메시지를 모달이나 토스트 메시지로 명확하게 표시합니다.

6. 백엔드 및 인프라 설계 (Simplified)

6.1. 디렉토리 구조

tech-stack.md에 제안된 가장 단순한 구조를 채택합니다.

airoum-landing/
├── app.py                 # 단일 파일 Flask 애플리케이션
├── requirements.txt       # 의존성 (Flask, Gunicorn)
├── templates/
│   └── index.html         # 메인 랜딩 페이지
└── static/
    └── css/
        └── style.css      # 스타일시트

6.2. 배포 전략

• 인프라: 자체 서버 + Nginx + Gunicorn
• 프로세스:
  1. GitHub에 코드를 Push합니다.
  2. 서버에서 Git Pull을 실행합니다.
  3. pip install -r requirements.txt로 의존성을 업데이트합니다.
  4. Gunicorn 서비스를 재시작하여 변경 사항을 적용합니다.
  • (주: CI/CD 파이프라인은 초기 단계에서 오버헤드가 될 수 있으므로, 수동 배포로 단순화합니다.)

7. 비기능적 요구사항 (Minimal)

• 로깅: Gunicorn과 Nginx의 기본 access/error 로그를 파일로 기록합니다. Flask 애플리케이션에서는 에러 발생 시에만 stderr로 로그를 출력합니다.
• 에러 핸들링:
  • 404 Not Found: Nginx 단에서 처리하거나, Flask에서 간단한 "페이지 없음" 메시지를 반환합니다.
  • 500 Internal Server Error: "서버 오류" 메시지를 반환하고, 상세 내용은 로그에만 기록합니다.