generated from Paul.Kim/tpl-superclaude
refactor(framework): Replace SuperClaude with Claude Flow & SPARC
This commit marks a significant architectural overhaul, replacing the legacy SuperClaude and Taskmaster AI frameworks with the new Claude Flow orchestration system and the SPARC/Roo methodology.
The new framework emphasizes parallel, swarm-based execution and mandatory batch operations for improved efficiency and coordination.
Key Changes:
- **Framework Migration:** The entire `.claude` and `.cursor` directories, containing the old command, persona, and rule systems, have been removed. They are replaced by the new `.roomodes` configuration and a comprehensive `CLAUDE.md` guide for Claude Flow.
- **New Orchestration Engine:** Introduced Claude Flow as the primary MCP server. The updated `CLAUDE.md` defines new rules for swarm orchestration, mandatory concurrent execution, and a clear separation of concerns between coordination (MCP) and execution (Claude Code).
- **Project Initiation (AIROUM):** Added extensive planning, design, and specification documents for a new project: the "AIROUM" educational landing page. This includes:
- Mood boards and multiple HTML design iterations in `.superdesign` and `gallery`.
- Detailed planning documents, technical designs, and pseudocode specs in `.taskmaster`.
- **Configuration Updates:**
- `.mcp.json` now points to `claude-flow` and `ruv-swarm`.
- `.gitignore` is updated to support the new Claude Flow file structure.
This commit is contained in:
151
.taskmaster/docs/technical-design-document.md
Normal file
151
.taskmaster/docs/technical-design-document.md
Normal file
@ -0,0 +1,151 @@
|
||||
# AIROUM 랜딩 페이지 기술 설계서 (v2.0 - Minimalist)
|
||||
|
||||
## 1. 프로젝트 목표 및 핵심 원칙
|
||||
|
||||
본 문서는 AIROUM 랜딩 페이지의 기술 설계를 정의합니다. v2.0 설계의 핵심 목표는 **'문의하기'라는 단 하나의 기능에 집중**하여, 가장 빠르고 안정적으로 사용자의 문의를 접수하는 것입니다. 모든 부가 기능(회원가입, 관리자 페이지 등)은 의도적으로 배제하여 복잡성을 최소화합니다.
|
||||
|
||||
* **단일 책임 원칙 (Single Responsibility):** 이 시스템의 유일한 책임은 '문의 데이터 수신 및 저장'입니다.
|
||||
* **최소주의 아키텍처 (Minimalist Architecture):** 가장 필수적인 기술 요소만 사용하여 가볍고 빠른 시스템을 구축합니다.
|
||||
* **사용자 경험 최우선 (UX First):** 기능이 단순한 만큼, 사용자의 첫인상을 결정하는 랜딩 페이지의 UI/UX와 성능을 최우선으로 고려합니다.
|
||||
|
||||
## 2. 시스템 아키텍처 (Simplified Architecture)
|
||||
|
||||
### 2.1. 아키텍처 다이어그램
|
||||
|
||||
```mermaid
|
||||
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):**
|
||||
```json
|
||||
{
|
||||
"name": "김에이",
|
||||
"email": "airoum.kim@example.com",
|
||||
"phone": "010-1234-5678",
|
||||
"message": "AI 윤리 교육에 대해 더 자세히 알고 싶습니다."
|
||||
}
|
||||
```
|
||||
* **Success Response (201 Created):**
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"message": "문의가 성공적으로 접수되었습니다."
|
||||
}
|
||||
```
|
||||
* **Error Response (400 Bad Request):**
|
||||
```json
|
||||
{
|
||||
"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`: "서버 오류" 메시지를 반환하고, 상세 내용은 로그에만 기록합니다.
|
||||
Reference in New Issue
Block a user