docs: アーキテクチャの概要

[kou029w]

アーキテクチャの概要

ARCHITECTURE.md を配置し、構成の概要とコードマップを記載しました。
目的: それぞれのレイヤーの境界と実際のコードとの対応関係を明確にすることによって初めてコードを触る開発者の理解を助ける目的。

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/ties-makimura/chibi-ch-i-lo/3j6vpFey15eibVmwt9NxuzkeV5VL
✅ Preview: https://chibi-ch-i-lo-git-docs-architecture-ties-makimura.vercel.app

[ties-makimura]

ログってどこで動いて出力する構成になっているのでしょうか？

[kou029w]

ログってどこで動いて出力する構成になっているのでしょうか？

Node.js の上で動いており、標準出力ですかね。
オンプレ環境であればホストシステムの logger コマンドによってNode.jsのプロセスの標準出力を syslog に書き込むという使い方を想定しております。

[ties-makimura]

Node.js の上で動いており、標準出力ですかね。

なるほど，全体構成見てログは触れてないのかなぁと見ていたのですが，chibichiloの外なんですね．

[dynamis]

オンプレ環境であればホストシステムの logger コマンドによってNode.jsのプロセスの標準出力を syslog に書き込むという使い方を想定しております。

ということはサーバの起動方法側の起動コード例からも読み取れはするのですが、もうちょっとだけ丁寧に書いて上げた方が良いかもですね。
https://github.com/npocccties/ChibiCHiLO/blob/master/server/README.md#%E8%B5%B7%E5%8B%95

ちなみにログの内容の詳細とかは Sphinx 側にあるわけですが、公開 README から非公開 docs を参照するのも変な気がします。その辺りはどうして欲しいですか？ > @yabuki
https://butterfly-docs.sphinx.cccties.org/Specs-Data.html?highlight=%E3%83%AD%E3%82%B0#id6

[dynamis]

自明にも思うけどコミットコメントルール (Conventional Commits) を追記したい？
https://github.com/npocccties/ChibiCHiLO/blob/master/README-ja.md#%E8%B2%A2%E7%8C%AE%E6%96%B9%E6%B3%95

「下記URL」といってるけどなにもない
https://github.com/npocccties/ChibiCHiLO/blob/master/README-ja.md#%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88

下記の URL から操作方法を学んでください

これは sphinx のことかな？どうしましょ？ > @yabuki

[yabuki]

自明にも思うけどコミットコメントルール (Conventional Commits) を追記したい？
https://github.com/npocccties/ChibiCHiLO/blob/master/README-ja.md#%E8%B2%A2%E7%8C%AE%E6%96%B9%E6%B3%95

「下記URL」といってるけどなにもない
https://github.com/npocccties/ChibiCHiLO/blob/master/README-ja.md#%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%88

下記の URL から操作方法を学んでください

これは sphinx のことかな？どうしましょ？ > @yabuki

今日、docs branchにつくった、V2.1/Design/に、非公開部分から古くなった部分や用語を現在に改めたものを移植します。
その作業が終わったら、gh-pages ブランチで公開しますんで、そちら側へリンクをお願いします。 @dynamis

ログの部分だけ急いでいるなら、先に作業しますけど。

[yabuki]

README-ja.md につけてる、学んでくださいの実際の参照先は、gh-pages のランディング・ページのurl か、V2.1/User/Manual/ の内容あたりか。

[dynamis]

ログの部分だけ急いでいるなら、先に作業しますけど。

いえ急ぎません。方針が分かれば十分です(と思う)。
ちなみに figma も言及がないが非公開だから書かない？公開部分ありましたっけ？

画像など静的ファイルの提供。UI のために使用。

差し替えやすいようにロゴ画像だけ入ってる状態だけど、どういう場合にどのようなディレクトリ構成で入れるべきとか方針あれば一言。

UI の設計や修正部分の探し方は懇切丁寧には書いてないですが Atomic Design Methodology を採用していて具体的な実装箇所は pages -> templates -> ... と見ていけばファイル名から分かるのだと思いますが、今のドキュメントとコードから読み取れますか？大丈夫ですか？ > @ties-makimura

あと私が見て自明では無さそう/貢献していくときに指針があると嬉しいと思った所少し > @kou029w

• シェアとかアクセス権限管理がどこでどう実装されているかは自明ではなく取っ付きにくそうな気がしました。コードをちゃんと読んでいけばすぐ分かる？
• server/services, server/config/routes 辺りについて、サーバの API/ルーティングの設計指針とか実装方針とかってありますか？

[kou029w]

@ties-makimura

ログってどこで動いて出力する構成になっているのでしょうか？

図中に追加しました。

---

@dynamis

差し替えやすいようにロゴ画像だけ入ってる状態だけど、どういう場合にどのようなディレクトリ構成で入れるべきとか方針あれば一言。

ありません。今あるロゴ画像 logo.png に関してはビルド手順にあるのでそちらへのリンクを追加しました。

画像など静的ファイルの提供。UI のために使用。ロゴ画像の差し替えはビルド手順を参照してください。

---

• シェアとかアクセス権限管理がどこでどう実装されているかは自明ではなく取っ付きにくそうな気がしました。コードをちゃんと読んでいけばすぐ分かる？

権限に関する説明をより詳細化、またUI側のセッションと権限の管理 (store/session.ts) への項目を追加しました。

server/services (code)

REST API の仕様と権限の宣言、主要なリクエストの処理と制御を行う。

server/auth (code)

リクエストの処理と制御のうち、認証に関わる処理を行う。

server/config/roles.ts (code)

利用者と LTI v1.1 ロールの完全修飾 URN との対応関係。権限の制御に利用。

store/session.ts (code)

セッションと権限の管理。

---

• server/services, server/config/routes 辺りについて、サーバの API/ルーティングの設計指針とか実装方針とかってありますか？

APIの設計指針としてはRESTなのでMDNのRESTのリファレンスを追加しました。

REST API の提供と静的ファイルの配信を担うサーバー。

実装方針に関してはFastifyのリファレンスに沿う、という方針くらいですかね。
読み返していて実装方針に関する説明が不足している印象あるのでもしかしたらあとで少し加筆しておくかもしれません。

[yabuki]

分かっている人向けとはいえ、アーキテクチャが、この短時間で残せたのは喜ばしい。

onBoarding 用のドキュメントを別の人が書く中で、本文書への追加要望はでるかもしれませんがシステムへのとっかかりができたと思います。

[yabuki]

draw.io で図をかいていますが、まあ有名というか、ググればでてくるからいいか。

electron の desktop version で扱っていますとかはあったほうがいいけど、誤差の範囲なんで approve です。

[horimasumi]

draw.io で図をかいていますが、

draw.io って，いいですよね．初めて見たとき，ブラウザで，ここまでできることに感動した．

[yabuki]

思い出した。いまは、Diagram Software and Flowchart Maker でしたっけ。offline でも図がかけるように、electron で動くバージョンがあるので、使って見てください。

Power point よりは、GitHub とかに貼り付けやすいです。 @horimasumi さん

draw.io って，いいですよね．初めて見たとき，ブラウザで，ここまでできることに感動した．

[ties-makimura]

UI の設計や修正部分の探し方は懇切丁寧には書いてないですが Atomic Design Methodology を採用していて具体的な実装箇所は pages -> templates -> ... と見ていけばファイル名から分かるのだと思いますが、今のドキュメントとコードから読み取れますか？大丈夫ですか？ > @ties-makimura

Atomic Design Methodology の意味を知っていればなんとなくイメージできますね！

[kou029w]

引き続き質問等あればできる限り回答・追記していくということでひとまずマージしますね。