포트폴리오: 사이버펑크

라이브 사이트 · 비공개 저장소

개요

• 역할: 독립 풀스택 및 크리에이티브 엔지니어.
• 현재 스택: Next.js 16 App Router, React 19, TypeScript, Tailwind CSS 4, MDX, next-intl, Framer Motion, Perlin-style distortion이 있는 custom Canvas waves, Three.js, React Three Fiber, provider-neutral AI integration, MCP/OAuth, Node.js 24 LTS, Vercel입니다.
• 결과: 포트폴리오 자체가 문서화된 제품인, 창의적 풀스택 엔지니어링의 살아 있는 증거입니다.
• 요약: 글리치 시각 언어, 편집형 읽기 경험, 제어된 통합을 하나의 일관된 제품으로 묶습니다.

제품 과제

• 과제: 개성과 기술적 깊이를 보여 주되 핵심 정보를 가리지 않아야 했습니다.
• 대상: 디자인과 아키텍처를 함께 검토하는 채용 담당자, 엔지니어링 관리자, 고객, 개발자입니다.
• 제약: 작은 화면, 키보드, reduced motion, 9개 언어, 외부 통합의 안전 경계를 동시에 충족해야 했습니다. 이 사이트는 명확성과 기술적 깊이를 모두 원하는 채용 담당자, 엔지니어링 관리자, 개발자, 잠재 고객을 위한 것입니다. 독특한 상호작용을 만들면서도 가독성, 반응형 사용, 모션 감소, 9개 언어 유지보수, AI와 통합의 안전한 경계를 지켜야 했습니다.

접근 방식과 결정

• 아키텍처: Next.js App Router가 현지화된 서버 문서와 route handler를 담당하고, 상호작용 셸은 클라이언트에 분리됩니다.
• 핵심 결정:
  • 9개 언어 콘텐츠와 라우팅: next-intl이 locale route와 messages를 담당하고, 프로젝트마다 현지화 MDX와 문서화된 영어 fallback을 둡니다.
  • Canvas와 3D 상호작용: Perlin-style distortion이 있는 custom Canvas waves, Framer Motion, 집중형 Three.js/React Three Fiber hero가 전체 제품을 3D scene으로 만들지 않으면서 expressive motion을 제공합니다.
  • FUI 진단 터미널: CRT 질감, scanlines, terminal status readout, glitch typography가 읽기 쉬운 hierarchy를 지키며 미래형 정체성을 만듭니다.
  • 선택적 음성 및 더빙: local browser feedback, dubbing popup, audio sequencing은 user settings와 browser support를 따릅니다.
  • 오버레이 조정: boot screen, navigation, cursor, scanlines, chat, dubbing popup, 3D hero는 fixed layer count가 아니라 의도적인 stacking coordination을 사용합니다.
  • Oz 어시스턴트 설계: /api/chat은 중립적인 주 서비스와 fallback 서비스 라우팅, 정적 포트폴리오 데이터와 심층 MDX 문맥, 명시적인 UI 도구를 사용합니다.
  • 클라이언트, 서버, 상태 경계: theme, 국제화, music provider는 분리하고 chat preference는 브라우저 로컬 상태에 두며 filter store는 좁은 역할만 맡습니다.
  • MCP와 OAuth: 읽기 전용 도구는 OAuth 2.1, PKCE S256, portfolio.read scope로 보호합니다.
• 트레이드오프: 전체 3D 경험 대신 목적 있는 Canvas와 선택적 3D를 택했고 브라우저 음성은 서버 음성 파이프라인이 아닌 선택적 피드백입니다.
• 데이터 흐름: 방문자 입력은 /api/chat으로 가고 정적 포트폴리오 데이터와 심층 MDX 문맥을 받습니다. 스트리밍 응답은 텍스트와 UI action을 반환하며 지원 브라우저는 선택적으로 로컬 음성을 사용할 수 있습니다.

진단형 디지털 글리치와 HUD 시각 시스템은 시스템, 라이트, 다크 테마에서 작동합니다. 맞춤형 Canvas 파도는 물리감과 Perlin 스타일 왜곡을 제공하며, React Three Fiber와 Three.js 히어로는 집중된 3D 레이어를 제공합니다. 서버 구조는 대화형 클라이언트 셸과 분리되어 있습니다. next-intl 라우트는 현지화된 MDX를 로드하고 영어를 콘텐츠 폴백으로 사용합니다.

결과와 증거

• 결과: 빠른 방향 안내와 시스템의 깊은 설명을 모두 제공하는 포트폴리오가 되었습니다.
• 품질과 검증: ESLint, TypeScript 검사, production build가 재현 가능한 검증 기준입니다.
• 보안 제어: chat은 signed temporary lockdown과 rate boundary를, MCP는 read-only scope와 one-time authorization code를 사용합니다.
• 비교와 진화: 이전 Portfolio: Glass에서 현지화된 편집형 설명과 agent access를 담는 더 모듈화된 제품으로 발전했습니다.
• 영향: 창의적인 frontend와 유지보수 가능한 콘텐츠, integration, security, deployment 판단을 함께 보여 줍니다.

기술 심층 분석

• 주요 세부 사항: CRT 질감, glitch typography, Canvas, 집중된 3D hero, music controls, locale-aware content가 과도한 전역 state 없이 역할을 나눕니다.
• 검증: lint, typecheck, production build를 반복 가능한 quality gate로 실행하고 responsive, reduced-motion, coarse-pointer 분기를 UI 변경 시 검토합니다.
• 최적화: client-only shell은 browser feature를 분리하고 MDX, data module, modular component는 필요 없는 상호작용을 줄입니다.
• 코드 품질: TypeScript type, 정돈된 handler, focused provider, 좁은 store, service/security module로 ownership을 명확히 합니다.
• 링크와 참고 자료: components/sections, components/ui, components/chatbot, components/providers, content/projects, messages, data, lib/mcp, lib/security, lib/services, stores를 참조합니다.

포트폴리오 어시스턴트 Oz

Oz는 중립적인 다중 서비스 라우팅과 제어된 폴백을 사용해 /api/chat에서 스트리밍합니다. 정적 포트폴리오 데이터와 심층 MDX 콘텐츠를 기반으로 답합니다. 로케일 인식 작업은 탐색, 프로젝트 검색, 연락, 음악, 테마, 언어 변경을 돕습니다. 선택적인 브라우저 음성 또는 더빙 피드백, 로컬 환경설정, 선택적 추론 또는 하위 에이전트 실행, 탈옥 또는 반복 악용을 위한 서명된 임시 잠금은 명확한 클라이언트와 서버 경계 안에 있습니다.

MCP 및 에이전트 접근

MCP 접근은 읽기 전용이며 OAuth 2.1 Authorization Code 흐름, PKCE S256, portfolio.read 범위로 보호됩니다. Streamable HTTP가 기본 전송입니다. OpenAPI, .well-known 검색, 에이전트 카드와 스킬 문서로 검색할 수 있습니다. Upstash Redis는 Vercel에서 원자적인 일회성 코드 교환을 제공하며, 로컬 폴백과 필요한 호환 엔드포인트가 있습니다.

지원 제품 시스템

Spotify 로그인, 콜백, 현재 재생 엔드포인트가 음악 경험을 지원합니다. SMTP 연락처 라우트는 통합 경계에서 보호를 적용합니다. Vercel Analytics와 Speed Insights, 분석 거부 기능이 포함됩니다. PWA manifest, JSON-LD, robots, sitemap, humans.txt, llms.txt, llms-full.txt, 현지화된 개인정보 및 법적 페이지도 제공합니다.

회고

• 다르게 할 점: 가장 무거운 visual path를 계속 단순화하면서 editorial personality를 유지합니다.
• 성공: interface, localized narrative, assistant, music, discovery가 하나의 제품처럼 작동합니다.
• 교훈: server integration, browser-only behavior, localized content의 경계가 명확할수록 rich interaction을 유지하기 쉽습니다. 클라이언트 애니메이션, 서버 통합, 현지화 콘텐츠를 분리하는 것이 가장 중요한 배움이었습니다. 이 포트폴리오는 상호작용, 콘텐츠 정확성, 통합 경계를 계속 다듬는 실용적인 공간입니다.

나의 기여

• 프론트엔드와 디자인: visual system, responsive section, HUD composition, Canvas, 3D hero, content presentation을 설계했습니다.
• AI와 Oz: streaming assistant surface, primary/fallback routing, portfolio와 MDX context, UI action을 구현했습니다.
• 상호작용과 애니메이션: motion, scroll, reduced-motion, responsive interaction을 조정했습니다. 제품과 디자인 시스템, 프론트엔드 상호작용, Canvas와 3D, 현지화 콘텐츠, Oz와 AI, MCP와 보안, 음악, 연락처, 분석, 검색 통합을 처음부터 끝까지 설계하고 구현했습니다.

아키텍처

• 계층 구조: server component는 locale과 문서 구조를, client component는 browser-only interaction을 담당하며 API route는 chat, contact, media, MCP를 분리합니다.
• 기능 모듈:
• app은 현지화된 페이지, API 핸들러, 검색 문서를 포함합니다.
• components는 섹션, UI, 챗봇, providers를 분리합니다.
• content, messages, data는 MDX, 번역, 검증된 사실을 저장합니다.
• lib은 MCP, 보안, 서비스를, stores는 맞춤 챗봇 필터 store를 담당합니다.
• 테마, 국제화, 음악은 각각의 provider를 사용하고 챗봇 세션 설정은 컴포넌트 로컬 브라우저 저장소에 둡니다.
• 상태 관리: provider context는 theme, locale, music을 소유하고 chat preference와 filter state는 필요한 범위에서만 유지됩니다.
• 리팩터링과 개선: 모듈 경계 덕분에 visual feature, route handler, content, integration이 독립적으로 발전합니다.

모듈과 운영 세부 사항

• src/app/[locale]은 localized pages, layouts, loading, error, project routes를 보유합니다.
• src/components/sections에는 Hero, About, Experience, Skills, Projects, Contact, Certification이 있습니다.
• src/components/ui는 GlitchText, Waves, CustomCursor, HeroModel, SkillGraph 같은 visual primitive를 제공합니다.
• src/components/layout은 navigation, boot experience, scroll-to-top behavior를 담당합니다.
• src/components/chatbot은 widget, conversation UI, client chat services를 분리합니다.
• src/components/providers는 client-only shell과 music-player provider boundary를 둡니다.
• src/content/projects는 locale별 project detail MDX source입니다.
• src/data와 src/messages는 verified static facts와 translation catalog를 둡니다.
• src/lib, src/hooks, src/stores는 shared service, reusable behavior, scoped UI/filter state를 담당합니다.
• route와 server component는 locale과 document structure를, client component는 interaction과 browser-only API를 담당합니다.
• theme과 provider state는 각자의 context를 사용합니다.
• chat preferences는 적절한 경우 component-local browser storage에 둡니다.
• filter store는 자체 UI concern에만 사용됩니다.
• Cover component는 media를 렌더하기 전에 server에서 local asset path를 확인합니다.
• internal navigation은 i18n routing module의 helper를 사용합니다.
• ghost navigation은 scroll-down에 숨고 scroll-up에 복귀합니다.
• body layout은 이 임시 navigation state를 보정합니다.
• contact form은 SMTP handler를 거치며 mail credentials를 client에 노출하지 않습니다.
• Spotify experience는 login, callback, now-playing endpoint를 사용합니다.
• /api/gallery/[slug]는 project media와 지원되는 project gallery를 위한 rate-limited surface입니다.
• 승인된 Oz UI action은 gallery가 enabled 및 supported일 때 project gallery를 열 수 있으며 universal mobile action으로 취급하지 않습니다.
• /api/chat은 same-origin requests를 검증합니다. abuse controls가 활성화되면 별도의 signed temporary lockdown cookie가 restriction을 전달하며 request 자체는 signed되지 않습니다.
• analytics에는 opt-out behavior가 있고 critical content와 분리됩니다.
• manifest, robots, sitemap, JSON-LD, localized metadata가 PWA와 SEO surface를 이룹니다.
• /[locale]과 project paths는 next-intl locale hierarchy를 제공합니다.
• /api/mcp, OpenAPI, .well-known은 read-only agent discovery를 제공하고 /api/chat은 Oz stream surface입니다.
• Oz 운영: /api/chat, /api/chat/health, /api/gallery/[slug]는 어시스턴트의 스트리밍, 상태 확인, rate-limited project-media surface를 제공하며, 승인된 UI 도구는 탐색, 프로젝트 필터링, enabled gallery, 연락처 검토, 음악, 테마, 언어 작업을 처리합니다.
• llms.txt, llms-full.txt, auth.md와 discovery documents는 LLM과 사람이 읽을 context를 제공합니다.
• authorization scope는 portfolio.read에 한정되어 MCP가 write surface가 되지 않습니다.
• one-time code redemption은 deployed environment에서 replay risk를 줄입니다.
• fallback provider는 availability를 보완하지만 portfolio source of truth를 바꾸지 않습니다.
• chatbot은 탐색과 검색을 도와도 content를 임의로 수정하지 않습니다.
• signed temporary lockdown은 jailbreak와 반복 abuse에 대한 경계를 제공합니다.
• visual primitive는 content model 변경 없이 독립적으로 시험하거나 끌 수 있습니다.
• Tailwind v4는 PostCSS configuration과 CSS token system을 사용합니다.
• TypeScript type은 portfolio data와 MDX module contract를 명확히 합니다.
• production build는 routes, content, server boundaries를 함께 확인하는 최종 단계입니다.
• static portfolio data는 page와 assistant가 같은 검증된 사실을 바라보게 합니다.
• MDX는 project narrative를 component presentation과 분리합니다.
• locale fallback은 콘텐츠 누락이 전체 route failure가 되는 일을 막습니다.
• server integration은 secret을 browser bundle 밖에 둡니다.
• interactive shell은 browser API가 필요한 때에만 hydrate됩니다.
• motion branch는 선호 설정을 존중하면서 기본 레이아웃을 유지합니다.
• semantic layout은 visual overlay가 있어도 reading order를 보존합니다.
• labelled control은 keyboard와 assistive technology의 사용성을 돕습니다.
• custom cursor의 부재는 touch device에서 정상적인 native pointer 경험을 유지합니다.
• 3D layer의 부재도 project details와 contact discovery를 방해하지 않습니다.
• content cover가 없을 때도 MDX document 구조는 유효하게 남습니다.
• localized metadata는 공유와 검색 결과의 언어 문맥을 맞춥니다.
• public discovery document는 agent integration의 계약을 명시합니다.
• OpenAPI는 machine-readable endpoint 설명을 제공합니다.
• OAuth client registration과 authorization flow는 일반 page navigation과 분리됩니다.
• Redis 사용은 Vercel 배포 환경의 code redemption 일관성을 위한 것입니다.
• local compatibility behavior는 개발 중 통합 확인을 가능하게 합니다.
• SMTP configuration과 API key는 .env로 관리하며 저장소에 포함하지 않습니다.
• Node.js 24 LTS는 package engines와 deployment runtime의 기준입니다.
• npm run lint는 style과 static analysis 문제를 찾습니다.
• npm run typecheck는 TypeScript contract를 검증합니다.
• npm run build는 production route와 bundle을 함께 검증합니다.
• 이러한 검증은 시각적 변화가 server integration을 깨뜨리지 않도록 돕습니다.

데모 미리보기

• 글리치 랜딩: 타이포그래피와 HUD 세부 요소, Canvas 질감은 콘텐츠의 우선순위를 지원합니다.
• Oz 대화: 스트리밍되고 locale-aware한 답변이 검증된 포트폴리오 문맥에서 제공됩니다.
• 프로젝트 탐색: MDX 사례, 커버 미디어, 구조화된 섹션이 프로젝트 그리드에서 상세 읽기로 이어집니다.
• FUI 진단형 랜딩: CRT 질감, scanline, 터미널형 status readout, glitch typography가 분명한 미래형 인터페이스 정체성을 만듭니다.
• 선택적 음성 및 더빙: 호환 browser는 사용자가 제어하는 local voice feedback과 dubbing popup을 제공할 수 있지만, audio는 사이트 사용의 전제 조건이 아닙니다.
• 반응형 그리드: projects, skills, experience, credentials는 fine pointer, touch, reduced-motion 환경에서도 읽기 쉬운 고밀도 section으로 구성됩니다.
• 현지화된 상세: 방문자는 선택한 언어로 같은 project architecture와 contribution narrative를 읽을 수 있습니다.
• 에이전트 준비형 발견: OAuth와 public discovery documents는 제한된 read-only machine access가 human-facing portfolio와 공존하는 방식을 설명합니다.
• 오버레이 조정: boot screen, navigation, cursor, scanlines, chat, dubbing popup, 3D hero는 읽기와 접근성을 유지하도록 의도적으로 stacking을 조정합니다.
• 비공개 코드베이스: public case study는 live product를 설명하고 codebase는 private로 유지합니다.

호스팅 참고: 이 코드베이스는 franzdomingo.dev의 문서화된 라이브 포트폴리오입니다.