動作の仕組みと技術スタック

LoPiQ は PC のローカル環境で「極めて軽快に動作する画像ビューア」を目指して設計されています。このページでは、全体のシステムアーキテクチャ図と、高速・軽量動作を実現している技術仕様について解説します。

🏗️ システムアーキテクチャ

LoPiQ は、Go 言語によるシングルバイナリの軽量サーバーと、HTMX を活用したブラウザフロントエンドで構成されています。外部データベースや重いランタイムに依存せず、OS 上で直接動作します。

graph TB
    subgraph Clients["📱 クライアント (LAN内デバイス)"]
        PC["💻 PC ブラウザ"]
        Mobile["📱 スマホ / タブレット"]
    end

    subgraph BrowserUI["🌐 ブラウザ UI"]
        UI["🎨 HTML / CSS / Vanilla JS"]
        HTMX["⚡ HTMX (HTML 差分更新)"]
    end

    subgraph Backend["🚀 LoPiQ バックエンド (Go シングルバイナリ)"]
        HTTP["HTTP サーバー (net/http)"]
        Auth["🔒 認証 (Auth Middleware)"]
        SSR["📄 テンプレート描画 (html/template)"]
        Scanner["📁 フォルダ走査 & 画像配信"]
        Runner["⚡ コマンド実行エンジン (Actions)"]
        AICli["🤖 AI アシスタント (OpenAI Client)"]
    end

    subgraph LocalEnv["💾 ローカル環境 / OS リソース"]
        Config["⚙️ 設定ファイル (config.json)"]
        Images["🖼️ ローカル画像フォルダ (PC / NAS)"]
        Shell["🐚 OS シェル (rm, trash, ffmpeg 等)"]
    end

    subgraph External["☁️ 外部サービス (任意)"]
        OpenAI["🤖 OpenAI API"]
    end

    PC --> UI
    Mobile --> UI
    UI --> HTMX
    HTMX <-->|"HTTP (HTML 差分取得)"| HTTP

    HTTP --> Auth
    Auth --> SSR
    Auth --> Scanner
    Auth --> Runner
    Auth --> AICli

    Scanner <-->|"直接読み込み / ZIP 化"| Images
    HTTP <-->|"読み込み / 保存"| Config
    Runner -->|"外部コマンド実行"| Shell
    AICli <-->|"API 呼び出し"| OpenAI

🔄 データフローと動作シーケンス

LoPiQ では、ブラウザとサーバー間のやり取りに HTMX を採用しており、SPA のようなリッチな操作性とサーバーサイドレンダリング（SSR）の軽快さを両立しています。

1. 画像一覧の閲覧と部分更新

sequenceDiagram
    autonumber
    actor User as ユーザー
    participant Browser as ブラウザ (HTMX)
    participant GoServer as Go バックエンド
    participant FileSystem as ローカルファイルシステム

    User->>Browser: フォルダ選択 / ページ移動
    Browser->>GoServer: GET /view?dir=... (HTMX リクエスト)
    GoServer->>FileSystem: ディレクトリ内の画像ファイルを直接スキャン
    FileSystem-->>GoServer: ファイル一覧
    GoServer->>GoServer: HTML 差分フラグメントをレンダリング
    GoServer-->>Browser: レンダリング済み HTML 差分
    Browser->>Browser: 対象 DOM 要素のみを瞬時に差し替え
    Browser-->>User: 画面の再読み込みなしで即座に表示

2. カスタムアクション実行

sequenceDiagram
    autonumber
    actor User as ユーザー
    participant Browser as ブラウザ
    participant GoServer as Go バックエンド
    participant Shell as OS シェル

    User->>Browser: アクションボタン（削除 / 変換等）をクリック
    Browser->>GoServer: POST /action/run (ファイル名 & コマンドID)
    GoServer->>Shell: 設定されたコマンドを実行 (例: trash "{file}")
    Shell-->>GoServer: 実行完了
    GoServer-->>Browser: 成功レスポンス (または次の画像 HTML)
    Browser-->>User: 次の画像へ自動遷移 / 一覧更新

💡 採用技術と設計の特徴

1. 超軽量な Go 製バックエンド

フレームワーク非依存: サードパーティの重い Web フレームワークに依存せず、Go の標準ライブラリ（net/http や html/template など）のみで実装されたシングルバイナリの HTTP サーバーです。
高速起動・低リソース: 実行ファイル単体で動作するため起動は一瞬であり、メモリや CPU の消費量も極めて低く抑えられています。データベース等のミドルウェアも一切不要です。
並行処理: フォルダ走査や画像配信、ZIP 圧縮処理など、Go の goroutine を活用して効率的に処理します。

2. HTMX によるスマートな画面遷移

HTML 駆動 (SSR): React や Vue などの巨大なクライアントサイドフレームワークを使用せず、軽量ライブラリ HTMX を採用しています。
スムーズな操作感: 画面の必要な部分だけをサーバー側でレンダリングした HTML 差分として非同期取得し、ブラウザ上で部分的に差し替えるため、SPA のような滑らかな操作感を提供します。

3. システムでの稼働管理

Linux (systemd): OS 標準のサービス管理機構に登録し、自動起動や Web 画面からのポート変更指示によるスムーズな自動再起動を保証します。
macOS (.app): 標準のアプリケーション起動プロセスとして、起動時に自動的にローカルサーバーをバックグラウンドで開始し、ブラウザで画面を開きます。

4. 開発プロセス

AI コーディングの活用: 本ソフトウェアの大部分は、AI コーディングアシスタントを活用して設計およびプログラミングされています。