アーキテクチャ概要（全体像） - basecamp/fizzy

システムアーキテクチャ概要

本システムは、Rails APIモードではなく、従来のモノリシックアーキテクチャ（サーバーサイドレンダリング + アセットパイプライン）をベースにしつつ、フロントエンドにHotwireスタックを統合したハイブリッド型です。データベース層では、SQLite 3の採用と、TrilogyによるMySQL接続、およびSolidシリーズによるジョブ・キャッシュ・ケーブルの管理が特徴です。

正在加载图表渲染器...

アーキテクチャの構成要素:

Webサーバー: リバースプロキシとして Thruster を配置し、アプリケーションサーバーである Puma へのトラフィックを最適化します (Gemfile:15-16)。
アプリケーション層: Rails 8の主要機能を担い、MVCパターンに従ってリクエストを処理します。全てのモデルは ApplicationRecord を継承し、データベース操作を抽象化します (app/models/application_record.rb:1-5)。
フロントエンド: Stimulus と Turbo により、HTML中心のインターフェースにリアクティブな振る舞いを付与します。JavaScriptバンドラーは不要で、Importmapによってモジュール管理を行います (Gemfile:8-11)。
バックエンドサービス: Redisに依存せず、データベースをバックエンドに利用した Solid Queue、Solid Cache、Solid Cable により、非同期処理、キャッシュ、WebSocket通信を実現します (Gemfile:17-19)。

技術スタックとフレームワーク構成

本プロジェクトの技術スタックは、Railsエコシステムの最新動向を反映しており、特に「シンプルさ」と「運用コストの削減」に重点が置かれています。

コアフレームワークとランタイム

Rails 8 (main): フレームワーク本体。GitHubのメインブランチを直接参照しており、最新の機能と改善を取り込んでいます (Gemfile:5)。
Puma: スレッドベースの高並行Webサーバー (Gemfile:16)。
Bootsnap: 起動時のコードロードを高速化するプリローダー (Gemfile:14)。

フロントエンドスタック

Hotwire (Turbo + Stimulus): サーバーサイドレンダリングの利点を維持しつつ、動的なWebアプリケーションを構築するためのスタックです (Gemfile:10-11)。
Importmap: JavaScriptのモジュール解決をNode.jsやbundlerなしで行う仕組みです (Gemfile:8)。
Propshaft: Sprocketsの後継となる、軽量なアセットパイプラインです (Gemfile:9)。

データベースとインフラ

SQLite3 (>= 2.0): 開発および運用環境における主要なデータベースエンジンとして採用されています (Gemfile:20)。
Trilogy: MySQL用の高速なRubyクライアントです (Gemfile:22)。
Solidシリーズ: Redisを別途管理するコストを削減するため、Active Job、Action Cable、キャッシュストアのバックエンドとしてデータベースを活用するライブラリ群です (Gemfile:17-19)。

運用・監視・デプロイ

Kamal: Dockerコンテナのデプロイを自動化するツールです (Gemfile:15)。
Mission Control Jobs: バックグラウンドジョブのダッシュボードを提供します (Gemfile:42)。
Autotuner: Pumaのスレッド数やワーカー数を自動的にチューニングするツールです (Gemfile:41)。

マルチテナントアーキテクチャ

本アプリケーションは、単一のインスタンス内で複数のテナント（顧客/組織）をホストする機能を備えています。この機能は、環境変数とConcernモジュールを組み合わせて実装されています。

テナントモードの制御

マルチテナント機能は、アプリケーションの起動時に config/initializers/multi_tenant.rb で設定されます。環境変数 MULTI_TENANT が "true" の場合、または設定ファイル内で config.x.multi_tenant.enabled が true に設定されている場合に有効化されます (config/initializers/multi_tenant.rb:1-5)。

この設定値は Account モデルのクラス変数に格納され、アプリケーション全体で参照可能になります。

Concernによる機能のカプセル化

マルチテナントに関連するロジックは、Account::MultiTenantable モジュール（Concern）に集約されています。このモジュールは ActiveSupport::Concern を使用して拡張されており、インクルード先のクラスにクラスメソッドとインスタンスメソッドを自動的に追加します (app/models/account/multi_tenantable.rb:1-13)。

サインアップ制御ロジック

最も重要な機能の1つが、新規ユーザー登録（サインアップ）の可否判定です。accepting_signups? メソッドは、以下のロジックでサインアップを受け付けるかどうかを決定します (app/models/account/multi_tenantable.rb:9-11)。

マルチテナントモードが有効な場合: 常にサインアップを受け付ける（true）。
マルチテナントモードが無効な場合:
- データベース内にアカウントが1つも存在しない場合（Account.none?）：最初のセットアップとしてサインアップを許可する（true）。
- すでにアカウントが存在する場合：サインアップを拒否する（false）。

このロジックにより、シングルテナントモードでは「最初の管理者のみが作成できる」状態を維持しつつ、マルチテナントモードでは誰でもアカウントを作成できるようになります。

データベース接続とモデル基盤

データ永続化層は、Rails標準のActive Recordパターンに基づいていますが、最新のRails 8の機能を活用し、レプリカデータベースへの接続設定が組み込まれています。

ApplicationRecordと接続設定

全てのモデルは ApplicationRecord クラスを継承します。このクラスは primary_abstract_class として定義されており、データベーススキーマの抽象化を担います (app/models/application_record.rb:1-2)。

また、configure_replica_connections メソッドが呼び出されています。これはRails 8で導入された（あるいはSolid Cache等の文脈で利用される）メソッドであり、データベースの読み取り操作をプライマリデータベースではなく、レプリカデータベース（読み取り専用コピー）に分散するための設定を行います (app/models/application_record.rb:4)。これにより、書き込みトランザクションの影響を受けずに、読み取りクエリのスケーラビリティを向上させることが可能です。

データベースドライバの選択

Gemfile には、複数のデータベースバックエンドに対応するためのドライバが含まれています。

SQLite3: バージョン2.0以上が指定されており、開発や小規模なデプロイメントにおける第一選択肢となります (Gemfile:20)。
Trilogy: MySQL向けのドライバであり、大規模な環境や既存のMySQLインフラを持組織向けの選択肢です (Gemfile:22)。

これらのドライバは、config/database.yml の設定に基づいて切り替えられますが、モデル層（ApplicationRecord）はその詳細を抽象化し、アプリケーションロジックからデータベースの種類を意識させない設計になっています。

フロントエンド制御層

フロントエンドの振る舞いは、主にStimulusコントローラーによって制御されます。これらのコントローラーは、Importmapを通じてブラウザにロードされます。

コントローラーの自動ロード機構

app/javascript/controllers/index.js は、フロントエンドJavaScriptのエントリーポイントの1つです。ここでは、@hotwired/stimulus-loading によって提供される eagerLoadControllersFrom 関数を使用しています (app/javascript/controllers/index.js:6)。

この関数は、Importmapで定義されたコントローラーファイル（controllers/**/*_controller）を検出し、アプリケーションの起動時にまとめて読み込み（Eager Load）、Stimulusアプリケーションに登録します (app/javascript/controllers/index.js:7)。

Hotwireとの統合

Stimulusコントローラーは、HTML内の data-controller 属性を持つ要素に対して自動的にアタッチされます。Turbo（Turbo DriveやTurbo Streams）によるページ遷移やDOM更新が行われた後も、Stimulusのライフサイクル管理により、コントローラーは適切に初期化・接続・切断されます。これにより、サーバーサイドから送信されるHTMLとクライアントサイドのインタラクションロジックがシームレスに連携します。

データフローとリクエストライフサイクル

ユーザーがアプリケーションにアクセスしてから、データが保存・表示されるまでの主要なデータフローを以下に示します。

正在加载图表渲染器...

データフローの詳細:

リクエスト受信: ユーザーからのリクエストは、まず Thruster を通過し、静的アセットの配信やHTTP/2のプッシュなどの最適化が行われます。
ルーティングとコントローラー: リクエストが Puma (Rails) に到達すると、ルーターによって適切なコントローラーとアクションに振り分けられます。
モデル層の判定: コントローラーがビジネスロジック（例：新規アカウント作成）を実行する際、Account.accepting_signups? メソッドを呼び出します (app/models/account/multi_tenantable.rb:9)。
データベースアクセス: ApplicationRecord を継承したモデルは、設定された接続（プライマリまたはレプリカ）を通じてデータベースにクエリを発行します (app/models/application_record.rb:4)。
レスポンス生成: コントローラーはビューをレンダリングし、HTMLを生成します。Turboを使用している場合、ページ全体の更新ではなく、部分的なHTML更新（Turbo Stream）がレスポンスに含まれることがあります。

コア設計における技術的決定事項

本アーキテクチャにおける重要な設計判断とその理由を以下にまとめます。

技術領域	採用技術	決定の理由とトレードオフ
フロントエンド	Hotwire (Stimulus + Turbo)	理由: JavaScriptのコード量を最小限に抑え、サーバーサイドのロジックを再利用できる。トレードオフ: 非常に複雑なクライアントサイドの状態管理には不向きだが、本プロジェクトの用途（汎用的なWebアプリ）には最適。
アセット管理	Importmap + Propshaft	理由: Node.jsやWebpackのビルドプロセスを排除し、デプロイを高速化・簡素化するため。トレードオフ: npmパッケージの依存関係管理が制限されるが、標準的なブラウザAPIやStimulusコントローラーで十分に対応可能。
バックグラウンドジョブ	Solid Queue	理由: Redisなどの外部依存サービスを運用せず、データベースのみで非同期処理を完結させるため。トレードオフ: Redisに比べスループットは劣る可能性があるが、運用コストと複雑さが大幅に削減される。
キャッシュストア	Solid Cache	理由: キャッシュ用の別途インフラを不要にし、データベースのストレージを活用するため。トレードオフ: メモリキャッシュ（Redis/Memcached）ほどの超高速性はないが、多くのWebアプリケーションにおいて十分な性能を発揮する。
WebSocket	Solid Cable	理由: Action CableのバックエンドとしてRedisを必要とせず、データベースを使用するため。トレードオフ: 接続数のスケーラビリティはRedisに劣るが、中小規模のアプリケーションや社内ツールでは問題にならない。
データベース	SQLite3 (Primary)	理由: 開発環境の簡素化、および単一データベースでの運用を可能にするため。トレードオフ: 書き込みスケーラビリティには限界があるが、Trilogyへの切り替えも容易に設計されている。
マルチテナント	環境変数 + Concern	理由: コードベースを変更することなく、デプロイ設定（環境変数）だけでシングル/マルチテナントを切り替えるため。トレードオフ: 複雑なテナント分離（DB分離など）は実装されていないが、アプリケーションレベルでの分離は提供される。
Webサーバー	Thruster + Puma	理由: ThrusterによるBrotli圧縮やHTTP/2/3の対応をフロントエンドに配置し、Pumaでアプリケーションロジックを処理するため。トレードオフ: 構成が少し複雑になるが、パフォーマンスとセキュリティの向上が見込める。

モジュール依存関係図

システム内の主要なモジュール間の依存関係を示します。データの流れと制御の流れを理解するために重要です。

正在加载图表渲染器...

依存関係のポイント:

設定からモデルへの注入: Gemfile で定義されたライブラリがロードされた後、config/initializers/multi_tenant.rb が実行され、Account モデルの挙動（マルチテナントかどうか）が決定されます (config/initializers/multi_tenant.rb:1-5)。
Concernのミックスイン: Account モデルは Account::MultiTenantable モジュールをインクルードすることで、accepting_signups? などのメソッドを獲得します (app/models/account/multi_tenantable.rb:1-13)。
フロントエンドの独立性: フロントエンドのローダー（index.js）は、バックエンドのモデル層に直接依存しません。HTMLを介して間接的に連携します。
インフラの集約: Solidシリーズの各コンポーネントは、個別のRedis等ではなく、共通のデータベース（Database）に依存します。

まとめ

本プロジェクトのアーキテクチャは、Rails 8の「進化による簡素化」という哲学を体現しています。Solidシリーズによるインフラの統合、Hotwireによるフロントエンドの軽量化、そしてSQLite3の採用により、開発者は複雑なインフラ管理から解放され、アプリケーションのコアとなるドメインロジックの実装に集中できる環境が整っています。マルチテナント機能の実装も、重厚なライブラリではなく、Rails標準の機能（Concernや環境変数）を活用してシンプルに構築されている点が特筆されます。