jp-learning-progress 設計書

Appearance

ADR-0001: 技術スタック選定 ​

  • ステータス: Accepted（M1ドラフト）
  • 日付: 2026-04-15
  • 決定者: プロジェクトリード（要承認）
  • 参照: requirements.md / ia.md

背景 ​

ベトナム人実習生向け日本語学習進捗管理アプリを、モック優先で構築する。 営業資料としての利用、後続のフル実装への展開、運用コスト、チームのスキルを勘案して技術選定を行う。

決定 ​

レイヤー採用根拠
言語TypeScript型安全／チーム習熟／Next.js 標準
フロントエンドフレームワークNext.js 14+（App Router）SSR/SSG/静的書き出し／ルーティング／社内実績
UIライブラリReact 18Next.js 標準
スタイリングTailwind CSS + shadcn/ui高速プロトタイプ／デザインシステム適用容易
アイコンlucide-reactshadcn/ui 親和性
状態管理React Server Components + Zustand（必要時）最小限で開始
フォームReact Hook Form + Zod型整合＋バリデーション
チャートRecharts または Chart.jsSSR 互換・軽量
多言語next-intlApp Router 親和、日本語／ベトナム語
認証（将来）NextAuth（Auth.js）M1では未導入（モックでは疑似ロール切替で代替）
DB（将来）PostgreSQL + PrismaM1では未導入（モックはJSON／メモリ）
バックエンド（将来）Next.js Route HandlersM1では API モックのみ
ストレージ（将来）Cloudflare R2動画／画像
動画基盤（将来）Cloudflare Stream or YouTube Private決定は Q3
ホスティングCloudflare Pages（モック・設計書とも）社内標準・create-pages スキル連携
ドキュメントVitePressMarkdown 中心／Cloudflare Pages デプロイ容易
品質ESLint + Prettier + TypeScript strict標準
テストVitest（unit）、Playwright（E2E、将来）M1はunit最小
CIGitLab CI社内標準

M1 スコープでの具体構成 ​

jp-learning-progress/
├── docs/                    # VitePress 設計書
├── mock/                    # Next.js モック
│   ├── app/                 # App Router
│   ├── components/          # UI コンポーネント
│   ├── lib/                 # モックデータ・ユーティリティ
│   └── public/
└── DESIGN.md                # create-design スキル生成
  • モックはすべて 静的書き出し（next export or Pages static） で Cloudflare Pages 配信
  • 実データ接続・認証は行わない（ロール切替はクエリパラメータ or トップメニューで切替）
  • 動画は公開サンプル（YouTube／短いサンプルファイル）を用いた見た目のみ

代替案と却下理由 ​

代替却下理由
Remix社内実績・学習コスト面で Next.js 優位
Nuxt/Vue社内の Next.js 実績・周辺ツール成熟度
Hugo/VitePress のみで構築動的UI（クイズ／視聴ログ）で表現力不足
Firebase + Reactベンダーロック／将来のバックエンド柔軟性で PostgreSQL を優先
Strapi/DirectusM1 で不要、過剰スコープ

影響・制約 ​

  • モック段階で実データを扱わない方針のため、個人情報の流入リスクなし
  • 実装フェーズ移行時に認証・DB・API を段階的に導入する（別ADR）
  • Cloudflare Pages の SSR 制限（限定実行環境）は M1 では問題にならない
  • 将来的に NextAuth / Prisma を採用する際、Node ランタイム要件（Cloudflare Pages Functions）を再評価

ホスティング移行戦略（Cloudflare Pages → ？） ​

Cloudflare Pages Functions は実行環境（Workers ランタイム）に制約があり、NextAuth 一部プロバイダ・Prisma・重いサーバ処理と衝突し得る。以下を移行判断トリガーとして事前合意する。

トリガー判断
Prisma（Node API）必須の処理が増えるPages → Vercel または Node 実行基盤（AWS/Render 等）を再評価
NextAuth の選定プロバイダが Edge で動かない同上
動画処理・バックグラウンドジョブが必要キュー基盤（別インフラ）導入を検討
レスポンス 5MB／実行時間 30s 等のCF Pages 制約に抵触Pages Functions は軽量APIのみに限定し、重処理は外出し

M1 の範囲では実データ／認証／DB を扱わないため、上記トリガーは発生しない。M2 着手時に上記を ADR-000x で正式決定する。

未確定事項 ​

  • Q3（動画プラットフォーム）次第で、動画再生 UI ライブラリを決定
  • 分析・可視化の規模が大きくなる場合、Recharts から ECharts 等への移行を再評価
  • M2 時点でのホスティング移行可否（上記トリガー表参照）

レビュー ​

  • フロント：要レビュー
  • セキュリティ：要レビュー（Cloudflare Pages 上での同意フロー、Cookie 属性等）
  • 営業：開示可能な技術情報の粒度を合意要

Internal — thriveJobs

© 2026 thriveJobs