Portfolio: Cyberpunk

LIVE SITE · 非公開リポジトリ

概要

• 役割： 一人で担当したフルスタック／クリエイティブエンジニア。
• スタック： 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 言語、外部連携の安全境界を同時に満たす。

アプローチと判断

• アーキテクチャ： Next.js App Router がローカライズされたルートとサーバーコンテンツを担当し、操作部分は独立した client shell に置く。
• 主要な判断：
  • 9 言語のコンテンツとルーティング： next-intl が locale route と messages を担い、各 project はローカライズ済み MDX と文書化された英語 fallback を持つ。
  • Canvas と 3D の操作： Perlin-style distortion を持つ custom Canvas waves、Framer Motion、焦点化した Three.js/React Three Fiber hero が expressive motion を加え、製品全体を 3D scene にはしない。
  • FUI diagnostic terminal： CRT texture、scanlines、terminal status readout、glitch typography が未来的な個性を作り、読みやすい hierarchy を保つ。
  • Optional voice と dubbing： local browser feedback、dubbing popup、audio sequencing は user settings と browser support に従う。
  • Overlay coordination： boot screen、navigation、cursor、scanlines、chat、dubbing popup、3D hero は fixed layer count ではなく意図的な stacking coordination を使う。
  • Oz assistant の設計： /api/chat は中立的な primary/fallback service routing、static portfolio data と深い MDX context、明示的な UI tools を使う。
  • client、server、state の境界： provider は theme、国際化、music を分離し、chat preference はローカルに置き、filter store は狭い責務だけを持つ。
  • MCP と OAuth： read-only tools は OAuth 2.1、PKCE S256、portfolio.read scope で保護する。
• 国際化： next-intl がルート、messages、metadata、project MDX を扱い、存在しない項目は英語へフォールバックする。
• Canvas： 波と歪みは UI レイヤーに閉じ、コンテンツルートをアニメーションの寿命に結び付けない。
• 3D hero： Three.js と React Three Fiber は適したクライアント文脈でのみ読み込み、可読性の前提にしない。
• デザインシステム： CSS custom properties と共有 glitch primitives で色、書体、overlay、状態フィードバックを揃える。
• アクセシビリティ： reduced-motion の分岐を持ち、coarse pointer では custom cursor を表示しない。
• トレードオフ： Canvas、audio、3D がなくても利用できる progressive enhancement を選んだ。
• トレードオフ： 全面 3D ではなく目的のある Canvas と選択的な 3D を選び、browser voice は server speech pipeline ではなく任意の feedback とする。
• データフロー： 訪問者の入力は /api/chat に届き、static portfolio data と深い MDX context を受ける。streaming response は text や UI action を返し、対応 browser は任意で local voice を使える。

結果と根拠

• 成果： 速い方向付けと、背後の system を深く説明する読み物を両立した。

• 品質と検証： ESLint、TypeScript check、production build は再現可能な quality gate である。

• セキュリティ controls： chat は signed temporary lockdown と rate boundary を、MCP は read-only scope と one-time authorization code を使う。

• 比較と進化： 以前の Portfolio: Glass から、ローカライズされた narrative と agent access を扱える modular portfolio へ進化した。

• 影響： creative frontend と、保守可能な content、integration、security、deployment の判断を同時に示す。

• 最初の画面でアイデンティティと内容を伝え、必要に応じて深い操作層へ進める。

• Projects、Skills、Experience、Contact はアカウントなしで閲覧できる。

• 9 言語のルートで同じ情報階層を維持している。

• Oz は検証済みの portfolio facts へ会話で案内する。

• 外部連携は必須条件ではなく、任意の拡張として扱う。

技術詳細

• 注目すべき詳細： CRT texture、glitch typography、Canvas、焦点化した 3D hero、music control、locale-aware content は、過剰な global state container なしに責務を分ける。

• 検証： lint、typecheck、production build を quality gate として実行し、responsive、reduced-motion、coarse-pointer branch を UI 変更時に確認する。

• 最適化： client-only shell が browser feature を隔離し、MDX、data module、modular component が不要な interaction の読み込みを避ける。

• コード品質： TypeScript type、整理された handler、focused provider、narrow store、service/security module が ownership を明確にする。

• リンクと参照： components/sections、components/ui、components/chatbot、components/providers、content/projects、messages、data、lib/mcp、lib/security、lib/services、stores を参照する。

• /api/chat は multi-provider routing と制御された fallback による Oz のストリーミング応答を提供する。

• アシスタントは静的 portfolio data と MDX context を明確な参照元として利用する。

• browser voice は任意機能であり、speech が使えなくても text-first の体験を保つ。

• MCP は read-only、主な transport は Streamable HTTP、認可は OAuth 2.1 Authorization Code と PKCE S256。

• Vercel では Upstash Redis が atomic な one-time authorization-code redemption を担い、ローカル開発用の互換動作もある。

• theme、provider state、component-local browser persistence、chatbot filter store は役割ごとに分離される。

振り返り

• 異なる進め方： editorial personality を残しながら、負荷の高い visual path をさらに簡素化する。

• 成功： interface、localized narrative、assistant、music、discovery が一つの product として機能する。

• 学び： server integration、browser-only behavior、localized content の境界が明快なら rich interaction は維持しやすい。

• コンテンツ階層を先に置くと、創造的な動きは体験を本当に強くできる。

• 連携を増やすことより client と server の境界を明確にすることが重要だった。

• ローカライズされたケーススタディは、一度訳して終わりではなくコードと同期させる必要がある。

担当したこと

• frontend と design： visual system、responsive section、HUD composition、Canvas、3D hero、content presentation を設計した。

• AI と Oz： streaming assistant surface、primary/fallback routing、portfolio と MDX context、UI action を実装した。

• interaction と animation： motion、scroll、reduced-motion、responsive interaction を調整した。

• visual system、page structure、responsive interaction を設計・実装した。

• localized content pipeline、project presentation、MDX components を構築した。

• Oz assistant、AI provider fallback、security controls を統合した。

• MCP discovery、OAuth、contact、media、analytics、deployment integration を実装した。

プロジェクトアーキテクチャ

• レイヤー構造： server component が locale と document structure を、client component が browser interaction を担い、API route は chat、contact、media、MCP を分離する。

• 機能モジュール： 機能単位の Next.js 構成により、content、UI、server integrations、machine-readable discovery を分離している。

• レイヤー： route と server components が locale と document structure を管理し、client components が操作と browser-only APIs を管理する。

• 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 primitives。

• src/components/layout： navigation、boot experience、scroll-to-top。

• src/components/chatbot： widget、conversation UI、client chat services。

• src/components/providers： client-only shells と music-player provider boundaries。

• src/content/projects： locale ごとの project detail MDX。

• src/data と src/messages： verified static facts と translation catalogs。

• src/lib、src/hooks、src/stores： shared services、reusable behavior、scoped UI/filter state。

• 状態管理： provider は theme、国際化、music を所有し、chat preference と filter state は必要な範囲に限定する。

• リファクタリングと改善： モジュール境界により visual feature、route handler、content、integration は独立して進化できる。

state は一つの global bucket ではない。themes と providers は各 context を持ち、chat preferences は必要なときだけ browser-local に保存し、filter store は自分の UI のためだけに使う。

このモジュール構成なら、localized content や server contracts に触れずに visual effect や provider を交換できる。

ルートと公開面

• PWA と SEO： manifest、robots、sitemap、JSON-LD、localized metadata が browser と crawler を支える。
• 9 言語： /[locale] と project paths が next-intl により locale-aware なページ階層を提供する。
• MCP と AI： /api/mcp、OpenAPI、.well-known が read-only agent access を公開し、/api/chat が Oz stream surface となる。
• Oz の運用： /api/chat、/api/chat/health、/api/gallery/[slug] が assistant のストリーミング、ヘルスチェック、rate-limited project-media surface を提供し、承認済み UI tools が navigation、project filtering、enabled gallery、contact review、music、theme、language actions を扱う。
• LLM と人向け export： llms.txt、llms-full.txt、auth.md、public discovery documents が明確な context を提供する。

運用上の詳細

• layout が fonts、providers、localized metadata boundary を定義する。
• loading と error surface は route experience の一部で、別の demo screen ではない。
• project slug は詳細を描画する前に該当 locale の MDX source へ解決される。
• Cover component は media を描画する前に server で local asset path を確認する。
• 内部 navigation は i18n routing module の helpers を利用する。
• ghost navigation は scroll-down で隠れ、scroll-up で戻る。
• body layout はこの一時的な navigation state を補償する。
• contact form は SMTP handler を通り、mail credentials を client に公開しない。
• Spotify experience は login、callback、now-playing surface を用い、汎用 music API route は持たない。
• /api/gallery/[slug] は project media と対応 project gallery のための rate-limited surface である。
• approved Oz UI actions は 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 page content には含めない。
• PWA manifest は通常の browser flow を変えずに installable metadata を支える。
• JSON-LD は visible portfolio facts と整合する structured context を提供する。
• robots と sitemap route が public pages の発見可能性を保つ。
• security と OAuth discovery は client-only hints ではなく .well-known documents に置く。
• authorization scope は portfolio.read のままで、MCP を write surface にしない。
• one-time code redemption が deployed environment での replay risk を抑える。
• fallback provider は availability を補うが、portfolio source of truth は変えない。
• chatbot response は navigation や検索を支援しても、content を自由に書き換えない。
• optional reasoning と subagent behavior は有効な場合も明確な server-side controls を持つ。
• signed temporary lockdown は jailbreak と繰り返し abuse への境界を作る。
• visual primitive は content model を変えずに単独で test または disable できる。
• Tailwind v4 は PostCSS configuration と project CSS token system を通して動く。
• TypeScript types は portfolio data と MDX module contracts を明確にする。
• production build は routes、content、server boundaries を合わせて確認する最後の工程である。

デモプレビュー

• Digital glitch landing page： 明快な typography、HUD の細部、Canvas texture はすべて content を支える。
• Oz assistant： portfolio context から streamed で locale-aware な回答と navigation help を提供する。
• Project exploration： MDX case studies、cover media、structured sections が projects grid から深い閲覧へつなぐ。
• FUI diagnostic landing： CRT texture、scanlines、terminal 風の status readouts、glitch typography により、明確な未来的インターフェースの個性を作る。
• Optional voice と dubbing： 対応 browser では user-controlled の local voice feedback と dubbing popup を表示できるが、audio はサイト利用の前提ではない。
• Responsive grids： projects、skills、experience、credentials は、fine pointer、touch、reduced-motion の文脈で読みやすい高密度 section として整理される。
• Localized detail： visitor は選んだ言語で同じ project architecture と contribution narrative を読める。
• Agent-ready discovery： OAuth と public discovery documents は、制御された read-only machine access と human-facing portfolio の共存を示す。
• Overlay coordination： boot screen、navigation、cursor、scanlines、chat、dubbing popup、3D hero は、読みやすさと到達性を保つため意図的に stacking を調整する。
• 非公開コードベース： public case study は live product を説明し、codebase は private のままにする。

ホスティング： このポートフォリオは franzdomingo.dev で公開され、Vercel を deployment target、Node.js 24 LTS を runtime とする。