posimai-root/docs/master-architecture.md

# Posimai Project — マスターアーキテクチャドキュメント

最終更新: 2026-04-05
対象: Claude Code / Cursor / Antigravity / Gemini / 全 AI エージェント

**このドキュメントはプロジェクトの現状を一元管理します。実装の前に必ず読んでください。**

> メモ: このファイルは変更が発生するたびに更新する（CLAUDE.md のルールに明記済み）。
> 「最終更新」日付と内容を常に一致させること。

---

## 0. ビジネス体制（確定）

- **Eiji**: 共同経営者。VPS・DNS（soar-enrich.com）・Cloudflare 管理・対外窓口・代表。
- **mai**: プロダクト開発担当。アプリ設計・実装・AI 活用。
- インフラ・ドメイン共用は設計通り。「Eiji 依存リスク」ではない。

---

## 1. 全体構成図（2026-04-05 確定）

```
╔══════════════════════════════════════════════════════════╗
║  mai の開発環境（Windows 11 PC）                         ║
║  VS Code / Cursor / Claude Code CLI / Termius            ║
╚══════════════════════════════════════════════════════════╝
         │ git push（gitea + github の2リモート同時）
         ▼
╔══════════════════════════════════════════════════════════╗
║  コード管理（2リモート並行）                              ║
║  Gitea（Synology 内）  ←→  GitHub（posimai/ org）        ║
║  ローカルバックアップ          Vercel 自動デプロイトリガー ║
╚══════════════════════════════════════════════════════════╝
         │ GitHub push → Vercel 自動デプロイ
         ▼
╔══════════════════════════════════════════════════════════╗
║  フロントエンド（Vercel / CDN）                           ║
║                                                          ║
║  posimai.soar-enrich.com → posimai-dashboard（確定）     ║
║                                                          ║
║  全アプリ URL（*.vercel.app で稼働中・全 23 本 PWA）:     ║
║  brain / habit / pulse / feed / reader / journal         ║
║  brief / daily / ambient / veil / together / lens        ║
║  diff / clean / timer / digest / think / site            ║
║  events / maps / tech-events / analytics / roadmap       ║
║                                                          ║
║  【セルフホスト】posimai-dev（Ubuntu PC / Tailscale）     ║
║  https://ubuntu-pc-pc-mkm21cz79ys4.tail72e846.ts.net:3333║
║                                                          ║
║  【計画中】*.posimai.soar-enrich.com ワイルドカード DNS  ║
║  → Passkey の rpID 問題を解決・Eiji に依頼予定           ║
╚══════════════════════════════════════════════════════════╝
         │ https://api.soar-enrich.com/brain/api/...
         │ （2026-03-26 移行完了）
         ▼
╔══════════════════════════════════════════════════════════╗
║  バックエンド本番（VPS）— 2026-03-25 移行完了             ║
║  Ubuntu 25.04 / AMD EPYC 4コア / 5.8GB / 85.131.245.239 ║
║  共同開発者 Eiji 提供                                    ║
║                                                          ║
║  Nginx: api.soar-enrich.com → :8090                     ║
║                                                          ║
║  posimai-api（Node.js / Express / :8090）                ║
║  稼働中のエンドポイント:                                  ║
║  ・記事 /articles /save    ・Journal /journal/*          ║
║  ・RSS /feeds              ・Gemini AI /gemini/*         ║
║  ・認証 /auth/* (Magic Link + WebAuthn + Google/GitHub OAuth) ║
║  ・記事 /articles /save    ・Journal /journal/*          ║
║  ・RSS /feeds              ・Gemini AI /gemini/*         ║
║  ・TTS /tts/* ← VOICEVOX（:50021 稼働済み）             ║
║  ・Stripe Webhook /api/stripe/webhook（署名検証済み）    ║
║                                                          ║
║  PostgreSQL 16                                           ║
║  articles / journal_posts / users（plan/stripe列あり）   ║
║  site_config / reading_history                           ║
║  magic_link_tokens / passkey_credentials / auth_sessions ║
╚══════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════╗
║  Ubuntu PC — 開発 OS（常時稼働）                         ║
║  100.77.11.43 / ubuntu-pc-pc-mkm21cz79ys4.tail*.ts.net  ║
║                                                          ║
║  ・posimai-dev（:3333 HTTPS / Tailscale）                ║
║    → ブラウザ内ターミナル + Claude Code 統合 PWA         ║
║  ・posimai-station（/station）                           ║
║    → HDMI モニター全画面キオスク監視盤                   ║
║  ・Syncthing → Windows PC と双方向同期                   ║
║  ・GNOME 削除済み / Openbox + Chromium kiosk             ║
╚══════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════╗
║  Synology NAS — バックアップ & 開発支援                  ║
║  100.76.7.3 / posimai-lab.tail72e846.ts.net              ║
║  Tailscale VPN 経由のみアクセス可                        ║
║                                                          ║
║  ・Gitea（git バックアップサーバー）                      ║
║  ・posimai_api（旧 API・待機中・フォールバック候補）       ║
║  ・PostgreSQL 15（旧 DB・待機中）                         ║
║  ・Uptime Kuma（死活監視 / :3002）                        ║
╚══════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════╗
║  外部サービス                                            ║
║                                                          ║
║  【認証・稼働中】VPS 自前（Magic Link + WebAuthn +       ║
║                   Google OAuth + GitHub OAuth）          ║
║  JWT: { userId, sid, plan }（plan=free/premium）         ║
║  Resend: Magic Link メール送信（noreply@soar-enrich.com）║
║                                                          ║
║  【決済・テストモード稼働中】Stripe                       ║
║  月額¥500・Webhook で plan=premium に自動更新            ║
║  本番切り替え: Store デザイン確定・特商法記入後           ║
║                                                          ║
║  【稼働中】Supabase DB                                   ║
║  together のみ（リアルタイム同期）                        ║
║                                                          ║
║  Gemini API → VPS 経由（journal/pulse 等）               ║
║  Gemini API → フロント直接（think アプリのみ）           ║
║  Google Fonts（Inter）/ unpkg（Lucide @0.344.0 固定）    ║
╚══════════════════════════════════════════════════════════╝
```

---

## 2. アプリ一覧（全 27 本・2026-04-05 時点）

| アプリ | URL | 種別 | バックエンド | 備考 |
|--------|-----|------|-------------|------|
| posimai-dashboard | posimai.soar-enrich.com | Next.js | — | メインダッシュボード |
| posimai-analytics | analytics.vercel.app | Next.js | — | RFM 分析 |
| posimai-brain | brain.vercel.app | 静的 | VPS API | 記事管理 |
| posimai-feed | feed.vercel.app | 静的 | VPS API | RSS フィード |
| posimai-reader | reader.vercel.app | 静的 | VPS API | 記事リーダー |
| posimai-journal | journal.vercel.app | 静的 | VPS API | CMS エディタ |
| posimai-site | site.vercel.app | 静的 | VPS API | 公開ホームページ |
| posimai-together | together.vercel.app | 静的 | Supabase | リアルタイム共有 |
| posimai-daily | daily.vercel.app | 静的 | VPS API | ブリーフィング |
| posimai-brief | brief.vercel.app | 静的 | VPS TTS | 音声ブリーフィング |
| posimai-habit | habit.vercel.app | 静的 | localStorage | 習慣管理（Supabase 移行予定） |
| posimai-pulse | pulse.vercel.app | 静的 | localStorage | 気分記録（Supabase 移行予定） |
| posimai-think | think.vercel.app | 静的 | Gemini 直接 | AI 思考整理 |
| posimai-digest | digest.vercel.app | 静的 | Gemini 直接 | テキスト要約 |
| posimai-ambient | ambient.vercel.app | 静的 | open-meteo | 常時表示 |
| posimai-veil | veil.vercel.app | 静的 | — | アプリランチャー |
| posimai-roadmap | roadmap.vercel.app | 静的 | — | ロードマップ管理 |
| posimai-timer | timer.vercel.app | 静的 | — | タイマー |
| posimai-lens | lens.vercel.app | 静的 | — | EXIF 表示 |
| posimai-diff | diff.vercel.app | 静的 | — | テキスト差分 |
| posimai-clean | clean.vercel.app | 静的 | — | テキストクリーナー |
| posimai-events | events.vercel.app | 静的 | — | イベント情報 |
| posimai-maps | maps.vercel.app | 静的 | — | マップ |
| posimai-hotels | hotels.vercel.app | 静的 | — | ホテル価格 |
| posimai-tech-events | tech-events.vercel.app | 静的 | RSS | IT イベント |
| posimai-atlas | atlas.vercel.app | 静的 | VPS API | インフラ構成図・監視 |
| posimai-ui | ui.vercel.app | 静的 | — | 共有デザインシステム |

---

## 3. 認証フロー（確定）

```
方針（本番としてそのまま進化させる）:
  フロント → API Key or JWT (Magic Link) → VPS が検証
  ?init_key= URL → localStorage に保存・JWT 保有
  3ユーザー（mai / partner / musume）のみ対応
  メール送信: Resend API (noreply@soar-enrich.com)
  ※ Supabase Auth への移行計画は中止（完全自己ホスト化）

課題: WebAuthn (Passkey) には共通の rpID が必要
  → *.posimai.soar-enrich.com ワイルドカード DNS が必須
  → Eiji への依頼待ち
```

**自前認証化のため `X-API-Key`・`?init_key=`・localStorage ロジックは維持される。**

---

## 4. データ保存先まとめ

| 保存先 | アプリ | 状態 |
|--------|--------|------|
| VPS PostgreSQL | brain・journal・site・reading_history | 稼働中 |
| Supabase DB | together | 稼働中 |
| localStorage + VPS バックグラウンド同期 | habit・pulse | ローカルファースト（同期のみ） |
| localStorage（永続・移行しない） | veil 設定・timer 設定 | 確定 |
| データなし（都度処理） | diff・clean・lens・digest・think・timer 本体 | — |

---

## 5. デプロイパイプライン（確立済み）

```bash
git add .
git commit -m "feat/fix/chore: 変更内容"
npm run deploy   # = git push gitea main && git push github main
```

- `gitea` → `http://100.76.7.3:3000/mai/[app-name].git`（ローカルバックアップ）
- `github` → `https://github.com/posimai/[app-name].git`（Vercel 自動デプロイトリガー）
- `vercel --prod` 直接実行: **禁止**
- VPS バックエンド: `bash deploy-server.sh`（SSH 鍵認証・完全無人）

---

## 6. AI エージェント役割分担

| 担当 | 内容 |
|------|------|
| インフラ担当チャット | 認証実装・VPS デプロイ・DNS・server.js 変更 |
| UI 担当チャット | UX・デザイン・CLAUDE.md 適合・プライバシー表記・バグ修正 |

**UI 担当が触ってはいけないもの:**
`api.soar-enrich.com` URL / `X-API-Key` ヘッダー / `?init_key=` パラメータ / localStorage 認証ロジック / server.js・VPS・Docker 関連

---

## 7. 直近の確定事項（設計判断ログ）

| 日付 | 決定事項 |
|------|---------|
| 2026-03-25 | バックエンドを Synology → VPS（Eiji 提供）に移行完了 |
| 2026-03-26 | API URL を `posimai.soar-enrich.com` → `api.soar-enrich.com` に分離完了 |
| 2026-03-27 | 認証方式を Supabase Auth（Magic Link + Passkey）に確定 |
| 2026-03-29 | ベンダーロックイン回避のため Supabase 完全移行を中止。VPS 独自認証（Magic Link+Passkey）を正規方針として続行 |
| 2026-04-04 | Google OAuth + GitHub OAuth 実装完了・動作確認済み |
| 2026-04-04 | Stripe Webhook 実装完了・テスト決済で plan=premium 更新確認済み |
| 2026-04-05 | VOICEVOX VPS 稼働済み確認（:50021）|
| 2026-04-05 | Uptime Kuma ポートが 3001 ではなく 3002 と判明・Station 修正済み |
| 2026-04-05 | atlas.json v3・Dashboard timeline・BentoCard beta バッジ更新済み |
| 保留中 | *.posimai.soar-enrich.com ワイルドカード DNS（Eiji 依頼待ち） |
| 保留中 | Store デザイン確定（A/B/C/D から選定中） |
| 保留中 | 特商法ページ事業者情報記入（mai 作業） |
| 保留中 | Stripe 本番モード切り替え |
| 未決定 | どのアプリに premium 機能を実装するか（最重要課題） |

---

## 8. 絶対に守るルール（全 AI 共通）

1. **デプロイは `npm run deploy` のみ**（`vercel --prod` 禁止）
2. **絵文字禁止**（コード・UI・コメントすべて）
3. **アイコンは Lucide のみ**（`@0.344.0` 固定）
4. **デザイントークン変更禁止**（`--accent` 1行のみ例外）
5. **`git push origin` 禁止**（gitea と github の2リモートのみ）
6. **`api.soar-enrich.com` / 認証ロジックは UI 担当チャットが触らない**
7. **このファイルを変更したらすぐ「最終更新」日付を更新する**

---

## 参照ファイル一覧

| ファイル | 内容 |
|---------|------|
| `CLAUDE.md` | AI 向けプロジェクトルール（最優先） |
| `AGENTS.md` | CLAUDE.md の Cursor/Windsurf 向けコピー |
| `docs/master-architecture.md` | **このファイル**（インフラ・確定事項の一元管理） |
| `posimai-dashboard/src/data/projects.json` | 全アプリの一覧・ステータス・技術スタック |
| `_template/` | フル機能テンプレート |
| `_template-minimal/` | 単機能ツール用テンプレート |