posimai-root/docs/master-architecture.md

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

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

このドキュメントはプロジェクトの現状・課題・ロードマップを一元管理します。
実装の前に必ずこのファイルを読んでください。

---

## 0. Gemini 最新回答への批判的レビュー（2026-03-11）

Gemini が「Gemini 3.1 Flash-Lite（2026-03-03リリース）」「Gemini 3.1 Pro（2026-02-19リリース）」
と具体的な日付を断言しているが、**AI が自身のバージョンに関してハルシネーションを起こす
典型的なパターン** であり、鵜呑みにしてはならない。

| Gemini の主張 | 判定 | 理由 |
|---|---|---|
| "Gemini 3.1 Flash-Lite を 2026-03-03 に正式リリース" | 要検証 | Claude の知識カットオフ（2025年8月）以降の情報。公式確認必須 |
| "DeepSeek V3.2 は推測だったと認める" | 評価する | 自己訂正は誠実 |
| Docker Compose 設計案を提示 | 方向性は正しい | ただし不完全（後述） |
| Ollama の導入 | 有効な提案 | RAM 要件の言及が不足 |

**AI モデルのバージョン情報は必ず公式で確認すること:**
- Google AI Studio (aistudio.google.com) でモデル一覧を確認
- DeepSeek 公式 API ドキュメントで最新版を確認

**Gemini の docker-compose.yml の問題点:**
- nginx（リバースプロキシ）がない → ポートが直接露出する
- Gitea がない → すでに動いているなら Compose で管理すべき
- ネットワーク定義がない
- restart ポリシーがない（NAS 再起動後にコンテナが自動起動しない）
- Ollama の GPU/メモリ設定がない
- secrets 管理が平文環境変数のみ（DB パスワード等）

---

## 1. プロジェクト全体像

### 1.1 所有者プロフィール
- 非エンジニア（コードを読める、書けない）
- AI エージェントへのプロンプト設計が得意
- クラウド依存なし・Synology ファーストが絶対条件
- コスト最小化・利用回数の上限を気にしたくない

### 1.2 現在のアプリ一覧（全 9 本）

| アプリ | ディレクトリ | 種別 | Synology 依存 | 状態 |
|--------|-------------|------|--------------|------|
| posimai-brain | `posimai-brain/` | SPA (Vanilla JS) | Yes（記事 API） | 稼働中 |
| posimai-feed | `posimai-feed/` | SPA (Vanilla JS) | Yes（フィード API） | 稼働中 |
| posimai-events | `posimai-events/` | 静的 (Vanilla JS) | 部分的 | 稼働中 |
| posimai-hotels | `posimai-hotels/` | 静的 (Vanilla JS) | 部分的 | 稼働中 |
| posimai-maps | `posimai-maps/` | 静的 (Vanilla JS) | 部分的 | 稼働中 |
| posimai-reader | `posimai-reader/` | 静的 (Vanilla JS) | No | 稼働中 |
| posimai-together | `posimai-together/` | 静的 (Vanilla JS) | No | 稼働中 |
| posimai-dashboard | `posimai-dashboard/` | Next.js (App Router) | 不明 | 稼働中 |
| posimai-analytics | `posimai-analytics/` | Next.js (App Router) | 不明 | 稼働中 |

### 1.3 アプリ種別の正確な分類

```
純粋な静的アプリ（Synologyなしでも全機能動作）
  → reader, together
  → データはコード内 or 不要

データ参照型（Synologyが落ちてもUIは動く・データだけ取れない）
  → events, hotels, maps
  → Synology から定期取得、localStorage キャッシュあり

SPA + バックエンド依存（Synologyが必須）
  → brain, feed
  → Synology FastAPI が主データソース

Next.js（サーバーサイド処理あり）
  → dashboard（Basic Auth あり）, analytics
  → Vercel Edge で動作、Synology 依存は設計次第
```

---

## 2. 現在のインフラ構成（確認済み・2026-03-11）

```
[開発者PC（Windows 11）]
  ├ VS Code + Claude Code / Cursor
  ├ c:/Users/maita/posimai-project/ (ローカル作業)
  └ git push → Gitea(primary) + GitHub(mirror)

[Synology NAS「Mai_SVR」（自宅・常時稼働）]
  ├ 物理 RAM: 16 GB（現在 4.11 GB 使用中）
  ├ DSM: 7.3.2-86009 Update 1
  ├ Virtual Machine Manager
  │   └ Posimai_lab（VM）: CPU 2コア、RAM 4GB、ディスク 100GB
  │       ※ VM 内の詳細は未確認（OS 不明）
  └ Container Manager（Docker Compose）
      └── プロジェクト: posimai_lab（/volume1/docker/posimai_lab）
            ├── gitea         (gitea/gitea:1.21)  ← 稼働中 ✓
            ├── gitea_db      (postgres:15)        ← 稼働中 ✓ ※Gitea + API 共用
            ├── mcp_server    (node:20-slim)       ← 稼働中 ✓ AI エージェント連携
            ├── posimai_api   (node:20-slim)       ← 稼働中 ✓ 記事API・Geminiプロキシ
            └── ai_proxy      (python:3.11-slim)   ← 停止中 → 削除可

  外部アクセス: Tailscale（posimai-lab.tail72e846.ts.net）
  内部ポート: Gitea:3000, API:8090

[GitHub（クラウド）]
  └ private mirror（Vercel webhook用）

[Vercel（クラウド）]
  └ 全9アプリをホスト（静的ファイル配信 / Next.js SSR）
```

### 2.1 posimai_api の詳細（確認済み）

- **言語**: Node.js（Python/FastAPI ではなかった）
- **役割**: 記事保存・要約・Gemini API プロキシ
- **DB**: PostgreSQL（gitea_db と同一インスタンス、同一ユーザー共用）
- **認証**: API キー方式（pk_maita_ / pk_partner_ / pk_musume_）
- **CORS 許可**: posimai-brain, posimai-reader, posimai-feed
- **アクセス方法**: Tailscale 経由 HTTPS または 内部 HTTP:8090

### 2.2 現状の問題点（優先度順）

**問題1: シークレット管理 — 高優先**
- docker-compose.yml に DB パスワード・API キーが平文記載
- git commit するとパスワードが Gitea/GitHub に残る
- 対策: `.env` ファイルに分離、docker-compose.yml から変数参照に変更

**問題2: DB ユーザーの共用 — 中優先**
- Gitea と posimai_api が同一 postgres ユーザー（gitea）を使用
- 対策: posimai_api 専用ユーザー/DB を作成する

**問題3: posimai_api が HTTP のみ — 中優先**
- nginx がないため HTTPS 化されていない（Tailscale 経由なら許容範囲）
- 対策: nginx コンテナ追加（必要と判断したとき）

**問題4: アクセントカラーの不統一 — 低優先**
- Brain/Feed/Reader: `#818CF8`（Indigo）
- その他・テンプレート: `#6EE7B7`（Teal）
- 対策: 新規アプリは Teal 固定。既存は次回大改修時に統一。

---

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

```
コード変更
  ↓
git add . && git commit -m "feat: ..."
  ↓
npm run deploy
  = git push gitea main && git push github main
  ↓                               ↓
Gitea（自宅Synology）        GitHub（private mirror）
（プライマリ・ソースof真実）       ↓
                          Vercel webhook
                               ↓
                    https://[app-id].vercel.app
```

**絶対に守るルール:**
- `vercel --prod` 直接実行 → 禁止（GitHub push で自動デプロイ）
- `git push origin` → 禁止（gitea と github の2リモートを使う）
- デプロイは `npm run deploy` のみ

---

## 4. 新アプリ作成の自動化（確立済み）

```bash
bash scripts/new-app.sh <app-id> "<表示名>" "<説明>"
```

1. `_template/` をコピー（プレースホルダー置換）
2. Git 初期化 + 初回コミット
3. Gitea API でリポジトリ作成 → push
4. GitHub CLI でリポジトリ作成 → push
5. Vercel で GitHub 連携
6. git post-commit フック設置

---

## 5. テンプレート仕様（`_template/`）

### 5.1 デザインシステム（変更禁止トークン）

```css
--bg: #0D0D0D          /* ページ背景 */
--surface: #1A1A1A     /* カード */
--surface2: #252525    /* ネスト要素 */
--border: #2D2D2D      /* ボーダー */
--text: #F3F4F6        /* 主テキスト */
--text2: #9CA3AF       /* 副テキスト */
--text3: #6B7280       /* 弱テキスト */
--accent: #6EE7B7      /* Posimai Teal（アプリごとに1行変更可） */
--radius: 12px
```

- フォント: Inter (300/400/500/600)
- アイコン: Lucide のみ（stroke 1.5〜2.0）
- 絵文字: **絶対禁止**
- カラフルな配色: **禁止**
- バッジ: emerald（完了）/ amber（進行中）/ zinc（予定）の3色のみ

### 5.2 テンプレートの現在の機能（Phase 1 実装済み）

```
_template/index.html に含まれるもの:
  ├ header（52px glassmorphism）
  │   ├ PC展開時: ページタイトルのみ（アプリ名はサイドバーに）
  │   └ モバイル/折りたたみ時: アプリ名 + ハンバーガー
  ├ sidebar
  │   ├ accordion ナビセクション（折りたたみ対応）
  │   ├ nav-count バッジ（数値表示）
  │   └ フッター（アバター + ユーザー名 + 設定歯車）
  ├ settings-panel（右スライドアウト）
  │   ├ トグルスイッチ
  │   ├ API キー入力
  │   └ データ削除ボタン
  ├ main content
  │   ├ card / list-item / empty-state
  │   ├ btn-primary / btn-ghost / btn-danger
  │   └ badge-stable / badge-progress / badge-planned
  └ toast 通知
```

### 5.3 テンプレート Phase 2 候補（優先度付き）

| 優先度 | 機能 | 判断根拠 |
|--------|------|---------|
| 中 | SWR API クライアント（オプションファイル） | API ありアプリ専用。デフォルト OFF |
| 中 | Pull to Refresh（モバイル） | PWA の基本 UX |
| 低 | コマンドパレット（Cmd+K） | パワーユーザー向け |
| 低 | BroadcastChannel（タブ同期） | 必要なアプリで個別実装 |
| 低 | PWA Share Target | manifest.json のコメントサンプルとして |

---

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

| エージェント | 主な用途 | 得意なこと |
|---|---|---|
| **Claude Code** | 設計・実装・アーキテクチャ判断 | CLAUDE.md / LEARNINGS.md の遵守 |
| **Cursor** | 日常的な小改修・インライン編集 | IDE 内での素早い修正 |
| **Antigravity** | 自律エージェント実験 | 複数ファイル横断変更 |
| **Gemini** | レビュー・大コンテキスト分析 | プロジェクト全体の俯瞰 |

**注意**: Gemini はモデルバージョン・リリース日・具体的な数値を
ハルシネーションする傾向がある。重要な技術情報は公式で確認すること。

---

## 7. AI モデル戦略（コストゼロ・上限なし優先）

### 7.1 基本方針

「最新モデルを追いかけず、無料枠を確実に使い切る」

### 7.2 推奨スタック（2026年3月時点での合理的な選択）

| 役割 | モデル | 費用 | 上限 |
|------|--------|------|------|
| メイン（解析・生成） | Gemini Flash 最新版 | 無料枠 | 1分あたり RPM あり |
| コード論理検証 | DeepSeek V3 最新版 | 有料（格安） | 実質無制限 |
| 完全ローカル（上限なし） | Ollama on Synology | 0円 | なし（RAM 依存） |

**重要**: モデル名・料金は Google AI Studio および DeepSeek 公式で必ず確認すること。
本ドキュメントに特定バージョンを記載しない理由は、AI によるハルシネーションを防ぐため。

### 7.3 Ollama on Synology の実現可能性

| Synology モデル | RAM | 動作可能なモデル |
|----------------|-----|----------------|
| 4GB | Llama 3.2 3B（要確認） | 簡単な要約・コード補完 |
| 8GB+ | Llama 3.1 8B, Gemma 3 9B | 記事分析・コード生成 |
| 16GB+ | Mistral Nemo 12B 等 | ほぼ全用途をカバー |

→ Synology の RAM 容量を確認してから検討

---

## 8. Synology Docker 目標アーキテクチャ

### 8.1 現状（確認済み）
```
Container Manager / posimai_lab プロジェクト（稼働中）
  ├ gitea       ✓ Docker 化済み
  ├ gitea_db    ✓ PostgreSQL 稼働中（Gitea + API 共用）
  ├ mcp_server  ✓ MCP サーバー稼働中
  ├ posimai_api ✓ Node.js API 稼働中（記事・Gemini プロキシ）
  └ ai_proxy    × 停止中 → 削除可

主な改善余地: シークレット管理 / nginx / DB 分離
```

### 8.2 目標構成（Container Manager / docker-compose）

```yaml
# posimai-synology/docker-compose.yml（設計案）

services:

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./nginx/certs:/etc/nginx/certs:ro
    restart: unless-stopped
    depends_on:
      - posimai-api

  posimai-api:
    build: ./api
    environment:
      - DATABASE_URL=postgresql://posimai:${DB_PASS}@postgres:5432/posimai
      - GEMINI_API_KEY=${GEMINI_API_KEY}
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=posimai
      - POSTGRES_PASSWORD=${DB_PASS}
      - POSTGRES_DB=posimai
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U posimai"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped

  # Gitea（既にDockerなら統合、直インストールなら後回し）
  # gitea:
  #   image: gitea/gitea:latest
  #   ...

  # オプション: ローカル LLM（RAM 8GB以上推奨）
  # ollama:
  #   image: ollama/ollama
  #   volumes:
  #     - ollama_data:/root/.ollama
  #   restart: unless-stopped

volumes:
  postgres_data:
  # ollama_data:
```

**env ファイル（`.env`、gitignore 必須）:**
```
DB_PASS=xxxxxxxxxx
GEMINI_API_KEY=xxxxxxxxxx
```

### 8.3 nginx ルーティング設計（案）

```nginx
# /api  → posimai-api:8000
# /git  → gitea:3000（任意）
# Tailscale IP または特定ポートでのみ公開
```

### 8.4 実装ステップ（優先度順）

| 優先度 | タスク | 前提条件 |
|--------|--------|---------|
| 1 (高) | ai_proxy コンテナ削除 | すぐ実施可 |
| 2 (高) | docker-compose.yml の `.env` 分離 | シークレット管理改善 |
| 3 (中) | nginx 追加（HTTPS / リバースプロキシ） | Tailscale 運用継続なら低優先でも可 |
| 4 (中) | posimai_api 専用 DB ユーザー作成 | Gitea との DB ユーザー分離 |
| 5 (低) | Ollama 追加 | VM RAM を 8GB に増やしてから |

---

## 9. 未解決事項（要確認）

| 確認項目 | 判明状況 |
|---------|---------|
| Synology の RAM 容量 | ✓ 物理 16GB（VM に 4GB 割当）|
| FastAPI / Python | ✓ 不使用。Node.js (posimai_api) が担当 |
| データの保存形式 | ✓ PostgreSQL（gitea_db コンテナ）|
| Synology への外部アクセス | ✓ Tailscale（posimai-lab.tail72e846.ts.net）|
| Gitea は Docker か | ✓ Docker 化済み |
| VM（Posimai_lab）の OS・用途 | 未確認（SSH / VNC で確認要）|
| mcp_server の具体的な動作 | 未確認（どの AI エージェントが使っているか）|

---

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

1. **デプロイは `npm run deploy` のみ**（`vercel --prod` 禁止）
2. **絵文字禁止**（コード・UI・コメントすべて）
3. **アイコンは Lucide のみ**
4. **デザイントークン変更禁止**（--accent 1行のみ例外）
5. **`git push origin` 禁止**（gitea と github の2リモートのみ）
6. **AI のバージョン断言は鵜呑みにしない**（公式確認必須）
7. **Synology への直接インストール禁止**（今後は全て Docker 経由）

---

## 参照ファイル一覧

| ファイル | 内容 |
|---------|------|
| `CLAUDE.md` | AI 向けプロジェクトルール（最優先） |
| `AGENTS.md` | CLAUDE.md の Cursor/Windsurf 向けコピー |
| `LEARNINGS.md` | 過去のトラブル・解決策・設計判断ログ |
| `docs/master-architecture.md` | **このファイル** |
| `docs/template-features-analysis.md` | テンプレート機能優先度分析 |
| `docs/gemini-review-prompt.md` | Gemini へのレビュー依頼プロンプト |
| `_template/index.html` | PWA テンプレート（Phase 1 実装済み） |
| `scripts/new-app.sh` | 新アプリ作成自動化スクリプト |