Skip to content

DesignDoc.md

Latest commit

 

History

History
150 lines (104 loc) · 6.85 KB

DesignDoc.md

File metadata and controls

150 lines (104 loc) · 6.85 KB

ToyBox Frontend Design Doc

著者(更新履歴)

開発者

目次

  1. 目標
  2. 目標としないもの
  3. 背景
  4. システム概要
  5. アーキテクチャ設計
  6. セキュリティ
  7. 運用方針
  8. テスト方針
  9. 更新履歴

目標

このソフトウェアの目的は C3 部員の継続的な内部及び外部との交流であり、既存の Toybox の作品部分リプレイスを実現することがゴールである

目標としないもの

  • ブログの投稿プラットフォームとしての機能
  • ブログの投稿プラットフォームは別のシステムとして提供する予定である。そのためこのバックエンドは作品の取り扱いのみに集中する。

背景

このバックエンドのプロジェクトは前身となるバックエンドが既に作成されています。以下がリポジトリの URL です。 https://github.com/Kyutech-C3/ToyBox-frontend 前フロントエンドでは Vuejs が採用されており、作品投稿プラットフォームおよびブログ投稿プラットフォームとしての機能を提供していました。
しかし現 C3 部員に Vuejs を技術スタックとして得意な人がほぼ残っていないことやバグが多く残っていること、主要な開発メンバーの卒業することを理由に保守性の面で大きな困難を抱えています。
そのため現 C3 部員で扱える人が多い、扱う人が増えるであろう React に置き換えることで保守性を重視した再開発を進めて行くこととなった。

参考 URL

前 ToyBox バックエンド
前 ToyBox フロントエンド
現 ToyBox バックエンド
現 ToyBox フロントエンド

システム概要

このシステムは以下のようなアーキテクチャで提供されます。

toyboxtech.dwawio.png

フロントエンドの使用技術は以下の通りである

  • フレームワーク:Vite + React
  • ルーティング:react router dom
  • グローバル状態管理:Zustand
  • サーバー状態管理:swr
  • linter:biome
  • UI テスト:Storybook
  • API テスト:Jest
  • CI: github workflow + husky + lint-staged

これらの技術の選定基準は以下の通りです。

  • 開発環境の違いによって開発中に不具合が起こらないかどうか
  • 技術の習得難度が高すぎないか
  • 調べる上で情報を見つけやすいか
  • 継続的に開発する上で、一定のコードの質を担保できるかどうか

採用されていない類似技術については代替案の検討を参照。 アプリケーション、データベース共に Docker コンテナ内で動くことを想定されています。

アーキテクチャ設計

このプロジェクトでは長期開発する上で保守性を確保するため、features アーキテクチャを採用しています。 features アーキテクチャを採用した理由として以下のような要因があります

  • 機能に障害があった際、原因解明に必要なファイルが探しやすいと考えたため
src
├── assets
│   └── react.svg
├── features
│   ├── Header
│   │   ├── index.module.css
│   │   └── index.tsx
│   └── WorkIndex
│       ├── hook
│       ├── index.module.css
│       └── index.tsx
├── pages
│   └── TopPage
│       ├── index.module.css
│       └── index.tsx
├── shared
│   └── ui
│       ├── Card
│       └── Switch
├── types
│   └── work.ts
└── util
    └── fetchData.ts

assets ディレクトリ

ロゴ、ペイロード画像など配置するディレクトリ バンドルサイズの肥大化につながるので基本的に画像は webp の拡張子にすること

features ディレクトリ

一つの機能としての粒度として切り分けているコンポーネントフォルダ、カスタムフックを用意する場合は今回は features アーキテクチャを採用しているため、features 配下に、/hooks /store などのディレクトリを設けること。feature のコンポーネントのさらに切り分けを行う場合、再利用不可能であると考えられる場合はその feature のフォルダ配下にコンポーネントを作成すること。また再利用可能と考えられる場合は shared ディレクトリに作成すること。

pages ディレクトリ

page の構成を記述したファイルを格納しておくディレクトリ。 基本 page で多くの記述は行わず、features の要素を組み合わせ、ページを完成させるようにすること。

shared ディレクトリ

使い回しができる ui や type を配置しているディレクトリ

types ディレクトリ

全体で利用できる型の宣言は基本こちらで行うこと、それ以外はそれぞれの作業部分のディレクトリ配下に /type もしくは /store ディレクトリを配置すること

util ディレクトリ

使い回しができる関数を置いておくディレクトリ。名称が分かりにくくなる可能性があるので、まとめられそうな関数があれば、フォルダ、もしくは同じファイル上に記入を行うなどで対策を行うこと。

セキュリティ

このアプリケーションでは認証が必要になります。現時点では前 ToyBox と同様に Discord 認証のみを組み込むことを予定しています。Email 認証やその他の認証、SSO などは組み込みません。

運用方針

VPS 上で Docker を使い動かすことを想定しています。1 日に 1 度朝 5 時に DB に関してはバックアップを取得します。

テスト方針

主に UI テストの作成の優先度は低くし、api のテストが通ることを優先する。 UI テストの優先度を低くする理由としては更新の多い UI 分野においてテストを導入してしまうと、 フロントエンドとしての負担が大きくなり、コードの書き直しを行うたびに、変更点をテストにも反映するとなると、二人体制の開発では継続が厳しいと判断したからである。

更新履歴

2025/10/14 Semi-koron