アーキテクチャ

このページは、Crowi 2.0 (コードネーム Reignite) のコードベース全体の構造を俯瞰します。Crowi は Express + Swig + jQuery のレガシーモノリスから、Hono API + Next.js 16 フロントエンドへとリビルドされました (RFC-0006、2026-05-22 に完了)。

モノレポ構成

リポジトリは Turborepo + pnpm workspaces のモノレポです。

crowi/
├── apps/
│   ├── crowi-runner/        # リファレンス runner プロジェクト — full イメージの構築元 (@crowi/runner-app)
│   ├── crowi-runner-slim/   # 最小 runner プロジェクト — slim イメージの構築元 (@crowi/runner-app-slim)
│   └── crowi-site/          # crowi.wiki LP + ドキュメント (Next.js + Fumadocs, :4303)
└── packages/
    ├── api/                 # Hono 4 API (:4301) — plugin-free (SDK + コアのみ)
    ├── api-contract/        # Hono (@hono/zod-openapi) 契約 + Zod スキーマ
    ├── web/                 # Next.js 16 App Router フロントエンド (:4302)
    ├── collab/              # リアルタイム共同編集 (Hocuspocus) ライブラリ
    ├── runner/              # @crowi/runner: 設定ローダ + プラグインリゾルバ (createRequire)
    ├── plugin-api/          # プラグイン SDK (CrowiPlugin / レジストリ / context)
    ├── plugin-aws/          # AWS 系プラグインの共通資格情報ベース
    ├── plugin-storage-{local,aws-s3}/
    ├── plugin-search-{mongo,elasticsearch,opensearch}/
    ├── plugin-mail-{smtp,aws-ses,resend}/
    ├── plugin-renderer-{emoji,katex,plantuml,crowi-legacy}/
    ├── admin-cli/           # `crowi-admin` CLI
    └── tsconfig/            # 共有 tsconfig プリセット

3 つの大きな構成要素 — API (packages/api)、Web (packages/web)、API 契約 (packages/api-contract) — を中心に、プラグインと runner プロジェクト (apps/crowi-runner*) が周囲を固めています。

api は plugin-free です。@crowi/api は SDK (@crowi/plugin-api) とコアのみを同梱し、ドライバは一切含みません。プラグインは runner プロジェクト — @crowi/api と選んだ @crowi/plugin-* を依存に持ち、crowi.config.json (どのプラグインをロードし、各レジストリでどのドライバを使うか) と .env を持つ小さな npm プロジェクト — が所有します。api は起動時に @crowi/runner ライブラリが createRequire(projectDir) で runner プロジェクトの node_modules/ から列挙プラグインを解決するため、プラグインの追加・削除に api の再ビルドは不要です。apps/crowi-runner がリファレンス runner プロジェクトで (その crowi.config.json は apps/crowi-runner/crowi.config.json)、セルフホストする運用者は自前のものを用意します。

技術スタック

レイヤ	技術
API	Hono 4 + Mongoose + JWT 認証
Web	Next.js 16 (App Router, Turbopack) + React 19 + Tailwind CSS v4 + shadcn/ui + @tanstack/react-query
Site	Next.js 16 (静的エクスポート) + Fumadocs UI + i18n (ja / en)
共通	TypeScript 5.x strict、pnpm workspaces、Turborepo
Lint / Format	Biome (format) + ESLint (lint)、lefthook フック
テスト	Jest + supertest (API)。CI では `services.mongo` コンテナを使い、`mongodb-memory-server` はローカル開発専用のフォールバック

API サーバ (`packages/api`)

起動シーケンス

Crowi.init() が、おおむね次の順序でサブシステムを初期化します。

setupEncryption — 機密 Config 用の暗号鍵プロバイダを準備
setupDatabase — MongoDB へ接続
setupModels — Mongoose モデルを登録
setupRedisClient — Redis クライアントを接続
setupSessionConfig — セッション設定
setupConfig — Config コレクションを読み込み
migrateConfig — 設定の移行
runAwsConfigMigration — v1 の AWS 設定を移行 (プラグインより前)
setupRenderer — レンダラのコアパイプライン (TOC / wikilink / メンション / コードブロック) を登録
setupPlugins — @crowi/runner が解決したプラグインを起動
setupMailer / setupSlack — メール / Slack
setupDNSCache / setupLRU
buildServer — Hono サーバを構築

レンダラは プラグインより先に 起動します。これにより、プラグインへ渡すレジストリにはコアの登録が済んだ状態になり、レンダラプラグインはその上に追記できます。

ルーティング

API は次の 3 系統のルートを持ちます。

公開 Hono ルート (認証なし)
認証済み Hono ルート (jwtAuth(crowi) 配下、大半のページ / ユーザー / コメント系)
管理 Hono ルート (jwtAdminRequired(crowi) 配下 = JWT + user.admin === true)

エンドポイントのハンドラは hono/handlers/ 配下 (管理系は hono/handlers/admin/ 配下) にあります。Hono アプリは hono/app.ts で組み立てられ、ミドルウェアは hono/middleware/ に置かれます。

認証とモデル

認証は JWT (アクセストークン + リフレッシュトークン) です。Mongoose モデルには Page (grant 付き) / Revision / User / Comment / Bookmark / Like / Watcher / Notification / Activity / Config / Backlink / Share / Attachment などがあります。

機密設定 (OAuth シークレット、AWS キー、SMTP パスワード、Slack トークン) は AES-256-GCM で暗号化されます。詳細は設定の暗号化を参照してください。

リアルタイム共同編集

Hocuspocus は別プロセスではなく、@crowi/collab ライブラリとして api プロセス内に attach されます。api の http.Server を ws noServer モードで使い、/collab/* (共同編集) と /presence/* (RFC-0005 のページプレゼンス) のアップグレードを処理します。詳細はリアルタイム共同編集の運用を参照。

公式 Docker イメージ

公式イメージはいずれも packages/api/Dockerfile から、@crowi/api を直接ではなく runner プロジェクトを構築元としてビルドされます。

full (apps/crowi-runner から) — 12 個のファーストパーティドライバをすべて同梱します。ストレージ / 検索 / メールのドライバは crowi.config.json を編集するだけで切り替えられ、再ビルドは不要です。
slim (apps/crowi-runner-slim から) — 暗黙のデフォルト 3 ドライバ (storage-local + search-mongo + mail-smtp) のみで、MongoDB だけで動作します。独自のプラグインセットを組み立てたい運用者向けの最小の土台です。

api は Node ランタイムを必須とします (Workers では動作不可、Containers は可)。

Web フロントエンド (`packages/web`)

Web アプリはプラグイン依存がゼロの 独立した deployable です。api と HTTP で通信し、runner プロジェクトがどのドライバを読み込んだかは関知しません。Next.js 16 App Router を採用し、src/app/ 配下を 3 つの Route Group に分けています。

Route Group	内容	ゲート
`(public)/`	ログイン / 登録 / インストーラ	なし
`(auth)/`	通常のページ機能	`useAuth` によるリダイレクト
`(admin)/`	管理画面	`user.admin === true`

データ取得は @tanstack/react-query を全面的に使います。apiClientV2 (Hono RPC クライアント、hc<AppType>) は共有契約から生成され、フックは src/lib/use-*.ts に置かれます。共有 UI は components/ui/ (shadcn) と、LoadingSpinner / ErrorAlert / AccessDeniedCard / NotFoundCard などの横断的プリミティブで構成されます。

API 契約 (`packages/api-contract`)

すべての API 契約と Zod スキーマがここに集約され、tsup で CJS + ESM + .d.ts がビルドされます。契約は @hono/zod-openapi の createRoute(...) ルート定義で、/api/v2 配下にマウントされ、page・ user・bookmark・notification・admin・adminCrypto などのトップレベル名前空間ごとにまとめられます。Scalar API リファレンスは /api/v2/docs で公開されます。

契約を 1 箇所で定義することで、API 実装と Web のクライアント呼び出しが同じ型に対して整合します。契約を編集したら pnpm --filter @crowi/api-contract build で dts を再生成してください。

移行の経緯

Crowi 2.0 への移行は機能単位で進められました。レガシーの Express コントローラ + Swig ビューを Hono ハンドラ + Next.js ページとして再実装し、レガシーの Express マウント (/_api/*、/login など) は RFC-0006 の切り替えにあわせて 2026-05-22 に完全廃止されました。現状のフェーズ状況はリポジトリの TODO.md に記載されています。