Temple System Architecture

Posted Jan 10, 2026

By Zoe Jheng

8 min read

1. 專案目標與設計取向

Temple System 的核心目標，是在實體廟宇（NFC、RFID、QR）與數位系統之間，建立一個方便且具有互動性的服務平台。本專案並不是要把廟宇的所有儀式數位化，而是讓數位系統成為實體場域的延伸：協助記錄互動、呈現內容，並在需要時提供智慧化的解讀。

因此，整體設計取向不是「以系統為中心」，而是「以實體互動為中心」，數位系統只負責補強與連結。本專案的原始碼與部署設定可在 GitHub 查閱： 👉 Temple System GitHub Repository

2. 整體架構鳥瞰

graph TD
    %% 定義樣式
    classDef actor fill:#f9f,stroke:#333,stroke-width:2px;
    classDef frontend fill:#d4f1f9,stroke:#333,stroke-width:2px;
    classDef backend fill:#ddfdbc,stroke:#333,stroke-width:2px;
    classDef db fill:#f9d5e5,stroke:#333,stroke-width:2px;
    classDef infra fill:#eee,stroke:#333,stroke-width:2px;
    classDef external fill:#ffffab,stroke:#333,stroke-width:2px,stroke-dasharray:5 5;

    %% 角色
    User(("一般信徒<br/>User/Believer")):::actor
    Admin(("廟方管理員<br/>Admin Staff")):::actor

    %% 外部服務
    subgraph External_Cloud["External Services"]
        LineAPI["LINE Platform<br/>(Login/Auth)"]:::external
        GeminiAPI["Google Gemini AI<br/>(Fortune/Content)"]:::external
    end

    %% 系統基礎設施
    subgraph System_Infrastructure["Temple System Infra"]
        Nginx["Nginx Reverse Proxy<br/>Gateway"]:::infra
        
        subgraph UI_Layer["Frontend Layer"]
            UserApp["User Frontend<br/>(api/frontend)<br/>Vite + React"]:::frontend
            AdminApp["Admin Dashboard<br/>(api/admin)<br/>Vite + React"]:::frontend
        end
        
        subgraph Logic_Layer["Backend Layer"]
            APIServer["Node.js Backend API<br/>(api/src)<br/>Express.js"]:::backend
            Prisma[["Prisma ORM<br/>(api/prisma)"]]:::backend
        end
        
        %% 資料庫使用原生圓柱形狀
        Database[("Database<br/>PostgreSQL")]:::db
    end

    %% 交互關係
    User -->|HTTPS Request| Nginx
    Admin -->|HTTPS Request| Nginx

    Nginx -->|Path: / or /app| UserApp
    Nginx -->|Path: /admin| AdminApp
    Nginx -->|Path: /api| APIServer

    UserApp -.->|Fetch /api| Nginx
    AdminApp -.->|Fetch /api| Nginx

    UserApp -->|"Generate Content"| GeminiAPI
    APIServer -->|"OIDC / Auth"| LineAPI

    APIServer -->|Data Access| Prisma
    Prisma -->|SQL Query| Database

本系統採用前後端分離 + Reverse Proxy + 容器化部署的架構模式：

所有請求先進入 Nginx（單一入口）
依路徑分流至：
- 使用者前端（User Frontend）
- 管理後台（Admin UI）
- 後端 API（/api）

後端 API 再負責：

與資料庫溝通
串接 LINE Login
呼叫 Google Gemini AI
處理籤詩、使用者、紀錄等邏輯

這種設計讓系統可以在不影響使用者介面的情況下，獨立擴充或重構後端與基礎設施。

3. 各層的責任邊界

整個系統被清楚劃分為幾個層級：

入口層（Nginx） 負責 HTTPS 與路徑轉發，將請求導向前端或 API，是整個系統的交通樞紐。

前端層（Frontend / Admin UI） 使用 Vite + React，負責互動、畫面與流程控制。

後端層（Node.js + Express） 提供 REST API，處理登入、抽籤、資料存取與外部服務串接。

資料存取層（Prisma ORM） 定義資料結構與關聯，負責將 API 操作轉為安全且一致的資料庫查詢。

資料庫層（PostgreSQL） 實際儲存使用者、籤詩、抽籤紀錄與互動資料。

這樣的分層設計讓每一層都能獨立演進，而不會互相綁死。

4. 籤詩資料如何進入系統

在 Temple System 中，籤詩不是寫在程式碼裡。它們來自整理過的 CSV 檔，匯入 PostgreSQL 成為結構化資料表。

每一支籤包含多個欄位，例如：

籤號、宮位、等級
詩文原文、白話解釋、總評
歷史故事與人生寓意
事業、感情、財運等運勢分類
問事情境標籤（考試、婚姻、搬遷…）

當使用者透過實體互動（例如 NFC 或 QR）觸發流程時：

系統取得對應的籤 ID
從資料庫撈出完整籤詩資料
將內容送給 Gemini AI 進行延伸解籤及白話說明
最終由前端呈現給使用者

資料驅動 + AI 輔助的內容，而不是一組硬寫在程式裡的文字。

5. 關於 `/api` 與目錄結構的設計選擇

在本專案的初期開發階段，前端（Frontend）、後台（Admin UI）與後端程式碼都被放在 /api 結構之下。這並不是一開始經過完整架構規劃後的選擇，而是開發初期對目錄命名與邊界意識不足所導致的結果。隨著系統逐漸成形，我開始意識到這樣的命名方式容易造成混淆： /api 同時代表「後端 API」與「整個應用程式目錄」，在概念上並不清楚，也不利於未來擴充與維護。然而，在嘗試重構時也發現，若要更動目錄結構或 API 路徑，將會迫使 Frontend 與 Admin UI 的所有請求路徑同步修改，反而會引入額外風險與不穩定性。因此在第一版架構中，選擇暫時保留現有結構，以確保系統能穩定運作與部署。這也成為一個重要的設計反思：即使是在小型專案中，目錄命名與路徑設計也是架構的一部分。未來若要進一步擴充或正式部署，本系統將會重新整理前端、後端與 Gateway 的邊界與命名方式，使其更清楚、可維護性更高。

6. 已知限制與未來改進方向

目前系統仍包含「隨機抽籤」的 API，這主要是開發與測試階段所使用的設計，但是，實際廟宇情境中還未得知是否能夠接受此功能。

因此未來將調整為：

以 實體互動（NFC、QR、IoT）作為主要觸發點
弱化或移除系統主導的隨機抽籤
讓數位系統專注在解籤、記錄與內容延伸

7. 專案所帶來的核心學習

透過 Temple System，實際整合：

前後端分離架構
Nginx Reverse Proxy
Node.js + Express API
Prisma ORM
PostgreSQL
Docker Compose
AI API 串接

但最重要的學習不是「用了哪些技術」，而是如何在專案中選擇合適的工具。

每個工具都很強種類也很多，但不是每個問題都需要最重的解法。真正困難的是在現實需求、文化情境與技術能力之間，找出一組剛好合適、又能成長的架構。

我認為這正是自己在 Temple System 這個專案最有價值的地方。

Project, Architecture

Node.js Express Docker Nginx PostgreSQL Prisma System Design

This post is licensed under CC BY 4.0 by the author.