16 KiB

Raw Blame History

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 scripts/new-app.sh <app-id> "<表示名>" "<説明>"

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

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

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

--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）

# 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 ルーティング設計（案）

# /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 共通）

デプロイは npm run deploy のみ（vercel --prod 禁止）
絵文字禁止（コード・UI・コメントすべて）
アイコンは Lucide のみ
デザイントークン変更禁止（--accent 1行のみ例外）
git push origin 禁止（gitea と github の2リモートのみ）
AI のバージョン断言は鵜呑みにしない（公式確認必須）
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`	新アプリ作成自動化スクリプト

16 KiB Raw Blame History Unescape Escape