"더빌딩(The BLDGS) 바이브 코더" 포지션 지원 프로젝트
💡 "완벽한 설계보다, 작동하는 프로덕트를 빠르게." Claude Code를 활용한 초고속 프로토타이핑 → 48시간 만에 구축한 프로덕션 레벨 풀스택 애플리케이션
🔗 Live Demo: https://maintenance-app-azure.vercel.app | 📚 API Docs: Swagger UI
| 항목 | 내용 |
|---|---|
| 프로젝트명 | AI 건물 유지보수 관리 시스템 (v2.0) |
| 개발 기간 | 2026.01.12 ~ 2026.01.14 (약 2일) |
| 개발 인원 | 1인 (기획, 디자인, 개발, 배포, 운영) |
| 핵심 가치 | AI Automation, Async Processing, Speed |
graph TD
Root((Maintenance AI))
Root --> A["AI 자동화"]
A --> A1["Groq Llama 3 기반"]
A --> A2["5개 카테고리 자동 분류"]
A --> A3["우선순위(Priority) 자동 산정"]
A --> A4["키워드 폴백(Fallback) 시스템"]
Root --> B["비동기 성능"]
B --> B1["Celery 작업 큐"]
B --> B2["Redis 메시지 브로커"]
B --> B3["응답 속도 25배 개선"]
B --> B4["WebSocket 실시간 알림"]
Root --> C["편의 기능"]
C --> C1["S3 현장 사진 업로드"]
C --> C2["모바일 반응형 UI"]
C --> C3["관리자 대시보드"]
C --> C4["상태 추적 (대기/진행/완료)"]
Root --> D["보안 & 인증"]
D --> D1["JWT 기반 로그인"]
D --> D2["RBAC (관리자/사용자 분리)"]
D --> D3["Rate Limiting (도배 방지)"]
- 사용자가 "수도꼭지에서 물이 새요"라고 입력하면 AI가 분석
- Category: plumbing (배관) / Priority: high (긴급) 자동 태깅
- Groq API 활용으로 0.5초 이내 초고속 분석
- AI 분석 등 무거운 작업은 백그라운드(Celery Worker)로 위임
- 사용자는 대기 시간 없이 0.1초 만에 응답(200 OK) 수신
- 분석 완료 시 WebSocket으로 결과가 실시간 팝업
- AWS S3(혹은 호환 스토리지) 연동으로 현장 사진 영구 보존
- Presigned URL 방식 혹은 서버 프록시 업로드 지원
flowchart LR
subgraph Client["💻 Frontend (Vercel)"]
Next["Next.js 14"]
Tailwind["Tailwind CSS"]
Zustand["React Query"]
end
subgraph Server["⚙️ Backend (Railway)"]
FastAPI["FastAPI"]
Celery["Celery Worker"]
Auth["JWT Auth"]
end
subgraph Infra["☁️ Infrastructure"]
Groq["Groq AI API"]
Redis["Redis Queue"]
S3["AWS S3"]
SQLite[("SQLite/PG")]
end
Next -->|REST API| FastAPI
Next <-->|WebSocket| FastAPI
FastAPI -->|Task| Redis
Redis -->|Process| Celery
Celery -->|Inference| Groq
FastAPI -->|Query| SQLite
FastAPI -->|File| S3
| 기술 | 버전 | 선택 이유 (Why?) |
|---|---|---|
| FastAPI | 0.115 | Python 비동기 처리에 최적화, 자동 문서화(Swagger) |
| Celery | 5.4 | 무거운 AI 작업을 백그라운드로 격리하여 사용자 경험 개선 |
| Groq | Llama3 | OpenAI 대비 4.6배 빠른 속도 및 무료 티어 활용 |
| Redis | 5.2 | 인메모리 메시지 브로커 및 캐싱 |
| 기술 | 버전 | 선택 이유 (Why?) |
|---|---|---|
| Next.js | 14 | 서버 사이드 렌더링(SSR) 및 강력한 라우팅 |
| Tailwind | 3.4 | 빠른 스타일링 및 반응형 디자인 구축 |
| React Query | 5.0 | 서버 상태 관리 및 캐싱 최적화 |
flowchart TB
subgraph User_Side
Browser["Web Browser"]
end
subgraph Cloud_Gateway
Nginx["Reverse Proxy"]
end
subgraph App_Cluster["Railway Container"]
API["FastAPI Server"]
Worker["Celery Worker"]
end
subgraph Data_Layer
Redis[("Redis Broker")]
DB[("SQLite/Postgres")]
ObjectStorage["AWS S3 Bucket"]
end
subgraph External_Service
AI_Model["Groq Llama-3-70B"]
end
Browser -->|HTTPS| Nginx
Nginx --> API
API -->|Async Task| Redis
Redis --> Worker
Worker -->|Inference| AI_Model
Worker -->|Update Status| DB
API -->|Read/Write| DB
API -->|Image Upload| ObjectStorage
sequenceDiagram
participant U as User
participant A as FastAPI
participant Q as Redis Queue
participant W as Celery Worker
participant G as Groq AI
U->>A: 1. 민원 제출 (POST /requests)
A->>Q: 2. 작업 등록 (delay)
A-->>U: 3. 즉시 응답 (202 Accepted)
par Background Process
W->>Q: 4. 작업 가져오기
W->>G: 5. AI 분석 요청
G-->>W: 6. 카테고리/중요도 반환
W->>W: 7. DB 업데이트
W-->>U: 8. WebSocket 알림 전송
end
- 문제 (Problem): LLM API 호출이 동기(Blocking)로 처리됨 (요청 시 3초 멈춤)
- 원인 (Cause): 단일 스레드/프로세스 모델에서 I/O Blocking 발생
- 해결 (Solution): Celery + Redis 도입
- 결과: 사용자 응답 시간을 2.5초 → 0.1초로 96% 단축
# Before (Blocking)
def create_request(data):
category = ai_model.predict(data.content) # 3초 대기
return db.save(data, category)
# After (Non-blocking)
def create_request(data):
process_ai.delay(data.id, data.content) # 0.01초 소요
return {"status": "processing"}| 항목 | OpenAI (GPT-4o) | Groq (Llama-3) | 결정 |
|---|---|---|---|
| 속도 | ~50 토큰/초 | ~300 토큰/초 | Groq 채택 |
| 비용 | 유료 | 무료 (Free Tier) | Groq 채택 |
- 이슈: Railway 배포 시 uvicorn 실행 시간이 오래 걸려 배포 실패
- 해결: CMD 명령어를 최적화하고
/health엔드포인트를 경량화하여 프로브(Probe) 통과
| 지표 (Metric) | v1.0 (Sync/OpenAI) | v2.0 (Async/Groq) | 개선율 |
|---|---|---|---|
| API 응답 속도 | 2,500ms | 100ms | 25배 ↑ |
| AI 처리 속도 | 2.3초 | 0.5초 | 4.6배 ↑ |
| 동시 처리량 | 4 req/sec | 98 req/sec | 24배 ↑ |
- Vector DB 도입: 과거 유사 민원 검색 (RAG)
- Slack 알림 연동: 관리자에게 실시간 알림
- 통계 시각화: Chart.js 기반 대시보드 고도화
maintenance-app/
├── 📂 backend/ # FastAPI Server
│ ├── 📄 main.py # Entry Point
│ ├── 📄 celery_app.py # Task Queue Config
│ ├── 📄 tasks.py # Async Tasks (AI Logic)
│ └── 📂 routers/ # API Endpoints
├── 📂 frontend/ # Next.js Client
│ ├── 📂 app/ # App Router
│ ├── 📂 components/ # Reusable UI
│ └── 📂 hooks/ # Custom Hooks (React Query)
└── 📂 .github/workflows/ # CI/CD Pipelines
# 1. Clone Repository
git clone https://github.com/doublesilver/maintenance-app.git
# 2. Run with Docker Compose (권장)
# Backend, Frontend, Redis, Worker가 한 번에 실행됩니다.
docker-compose up --build
# 접속 주소
# Frontend: http://localhost:3000
# Backend Docs: http://localhost:8000/docs"코드로 비즈니스 임팩트를 만드는 개발자"
이 프로젝트는 Claude Code와 AI-Driven Development 방법론을 적용하여, 통상 2주가 소요되는 풀스택 개발을 단 48시간 만에 완료했습니다.
- ✅ Speed: AI 코딩 도구를 활용한 광속 프로토타이핑
- ✅ Tech: FastAPI + Celery 비동기 아키텍처의 실무 적용
- ✅ DevOps: GitHub Actions & Railway를 통한 완전 자동화 배포
- ✅ Problem Solving: OpenAI 한계를 Groq 전환으로 극복
MIT License
Made with 💻 & ☕ by doublesilver