Coding Standard สำหรับ reverse proxy microservice stack

Core Principles

Repository Layout

templates/
  README.md
  add-service-checklist.md
  nginx/project-location.conf
  portal/card.html
  nextjs/
  vuejs/
  nuxt/
  nestjs/
  fastapi/
  golang/

services/
  docker-compose.yml
  docker-compose.local.yml
  nginx/
    nginx.conf
    conf.d/
      default.conf
      local.conf
  portal/
    index.html
  projects/
    demo1/
    task-assignee/
  templates/
    nextjs.compose.yml
    fastapi.compose.yml
    go.compose.yml
    microservice.compose.yml

root repo ใช้เก็บเอกสารระดับทีม เช่น README.md, AGENTS.md, handbook.html, deployment.html, standard.html และ starter scaffolds ใน templates/.

Routing Contract

Next.js Standard

Config

const basePath = process.env.NEXT_PUBLIC_BASE_PATH || "/projects/my-app";

const nextConfig = {
  output: "standalone",
  basePath,
  assetPrefix: basePath || undefined
};

Links and URLs

ใช้ next/link สำหรับ internal route ปกติ. ถ้าใช้ raw <a>, static public file, redirect, หรือ fetch ใน browser ต้องผ่าน helper กลาง เช่น withBasePath("/portal/plan").

import { withBasePath } from "@/lib/base-path";

await fetch(withBasePath("/api/db/events"), { method: "POST" });
<a href={withBasePath("/portal/plan")}>Research Plan</a>

Component Style

• แยก data helpers ไปไว้ใน lib/ หรือ data/.
• ใช้ TypeScript type สำหรับ payload และ domain object.
• หลีกเลี่ยง generated output เช่น .next/.
• ถ้า page เป็น client component ให้ keep state เฉพาะ UI state; business transformation ควรแยก helper.

Vue.js / Vite Standard

Vue.js services use Vite and must set base from VITE_BASE_PATH. Use a helper for raw anchors or browser fetches.

const base = process.env.VITE_BASE_PATH || "/projects/vue-demo/";

export default defineConfig({
  base,
  plugins: [vue()]
});

environment:
  PORT: 3100
  VITE_BASE_PATH: /projects/vue-demo/

Nuxt Standard

Nuxt services use NUXT_APP_BASE_URL so routes, assets, and API calls stay under /projects/<slug>/.

export default defineNuxtConfig({
  app: {
    baseURL: process.env.NUXT_APP_BASE_URL || "/projects/nuxt-demo/"
  }
});

environment:
  NITRO_HOST: 0.0.0.0
  NITRO_PORT: 3100
  NUXT_APP_BASE_URL: /projects/nuxt-demo/

NestJS Standard

NestJS APIs must honor BASE_PATH. The template uses app.setGlobalPrefix(), so nginx can preserve the external prefix.

const prefix = (process.env.BASE_PATH || "")
  .replace(/^\/+/, "")
  .replace(/\/+$/, "");

if (prefix) {
  app.setGlobalPrefix(prefix);
}

environment:
  PORT: 3100
  BASE_PATH: /projects/nestjs-demo

Python / FastAPI Standard

Runtime

services:
  fastapi-demo:
    expose:
      - "3100"
    environment:
      PORT: 3100
      ROOT_PATH: /projects/fastapi-demo
    command: >
      uvicorn main:app
      --host 0.0.0.0
      --port 3100
      --proxy-headers
      --forwarded-allow-ips="*"
      --root-path /projects/fastapi-demo

Code

import os
from fastapi import FastAPI

app = FastAPI(root_path=os.getenv("ROOT_PATH", ""))

@app.get("/healthz")
def healthz() -> dict[str, str]:
    return {"status": "ok"}

• ใช้ type hints ทุก public function.
• ใช้ Pydantic models สำหรับ request/response ที่ไม่ trivial.
• แยก router เป็น routers/, business logic เป็น services/, config เป็น settings.py.
• log เป็น structured fields เท่าที่ทำได้ เช่น request id, actor, action, status.

Golang Standard

Runtime

services:
  go-demo:
    expose:
      - "3100"
    environment:
      PORT: 3100
      BASE_PATH: /projects/go-demo

Code

package main

import (
    "log/slog"
    "net/http"
    "os"
)

func main() {
    port := getenv("PORT", "3100")
    basePath := getenv("BASE_PATH", "")

    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte(`{"status":"ok"}`))
    })

    slog.Info("server starting", "port", port, "basePath", basePath)
    if err := http.ListenAndServe(":"+port, mux); err != nil {
        slog.Error("server stopped", "error", err)
        os.Exit(1)
    }
}

func getenv(key, fallback string) string {
    if value := os.Getenv(key); value != "" {
        return value
    }
    return fallback
}

• ใช้ gofmt และ go test ./... ก่อนส่งงาน.
• ใช้ context.Context กับงาน IO หรือ request scoped work.
• ใช้ log/slog สำหรับ structured logging.
• อย่า hardcode public URL; อ่านจาก BASE_PATH หรือ X-Forwarded-Prefix.

Backend + PostgreSQL Standard

เมื่อ backend ต้องต่อ PostgreSQL ใน Docker Compose ให้ต่อผ่าน Docker service name ไม่ใช่ localhost.

Compose DB Service

<DB_SERVICE>:
  image: postgres:16-alpine
  container_name: <DB_SERVICE>
  restart: unless-stopped
  environment:
    POSTGRES_DB: <DB_NAME>
    POSTGRES_USER: <DB_USER>
    POSTGRES_PASSWORD: <DB_PASSWORD_ENV>
  volumes:
    - <DB_SERVICE>-data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U <DB_USER> -d <DB_NAME>"]
    interval: 10s
    timeout: 5s
    retries: 5
  expose:
    - "5432"
  networks:
    - <DOCKER_NETWORK>

Backend Connection

<APP_SERVICE>:
  environment:
    DATABASE_URL: postgresql://<DB_USER>:<DB_PASSWORD_ENV>@<DB_SERVICE>:5432/<DB_NAME>
  depends_on:
    <DB_SERVICE>:
      condition: service_healthy

Framework Usage

Data Safety

• ใช้ named volume สำหรับข้อมูล Postgres เสมอ.
• อย่า commit password จริงลง repo.
• อย่า publish 5432:5432 ใน production ยกเว้นมีเหตุผล admin ชัดเจน.
• migration ควรรันเป็น command/job แยก หรือ entrypoint ที่ idempotent.

nginx Standard

File Boundaries

• nginx.conf เท่านั้นที่มี events และ http.
• conf.d/*.conf ต้องเป็น server block เท่านั้น.
• proxy headers, timeouts และ Docker resolver อยู่ใน nginx.conf เป็นค่ากลาง.

Project Location Pattern

location /projects/demo1/ {
  set $demo1_upstream <APP_SERVICE>:3100;
  set $project_prefix /projects/demo1;
  proxy_pass http://$demo1_upstream;
}

Docker Compose Standard

services:
  my-demo:
    build:
      context: ./projects/my-demo
    restart: unless-stopped
    expose:
      - "3100"
    environment:
      PORT: 3100
      PUBLIC_BASE_PATH: /projects/my-demo
    networks:
      - <DOCKER_NETWORK>
    logging:
      driver: json-file
      options:
        max-size: "10m"
        max-file: "3"

• ใช้ expose สำหรับ service ภายใน proxy network.
• ใช้ ports เฉพาะ reverse proxy หรือกรณี debug เฉพาะกิจ.
• container name ควรอ่านออกและไม่ชนกันระหว่าง local/production.
• local compose ต้องไม่ต้องใช้ production certificate.

Docker Compose + Portal Setup Step By Step

ใช้ขั้นตอนนี้ทุกครั้งที่เอา service ใหม่เข้า stack. ตัวอย่างใช้ slug reports-demo.

Step 1: เลือก slug

reports-demo
/projects/reports-demo/

slug ต้องเป็น lowercase kebab-case และควรตรงกับ Docker service name.

Step 2: copy template

cp -R templates/nextjs services/projects/reports-demo
# หรือเลือก templates/vuejs, templates/nuxt, templates/nestjs, templates/fastapi, templates/golang

Step 3: เพิ่ม service ใน docker-compose.yml

reports-demo:
  build:
    context: <DEPLOY_PATH>/projects/reports-demo
  container_name: reports-demo
  restart: unless-stopped
  expose:
    - "3100"
  environment:
    PORT: 3100
    PUBLIC_BASE_PATH: /projects/reports-demo
  networks:
    - <DOCKER_NETWORK>
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

ใช้ expose ไม่ใช้ host ports สำหรับ app service ที่อยู่หลัง nginx.

Step 4: ตั้ง framework base path

# Next.js
NEXT_PUBLIC_BASE_PATH: /projects/reports-demo

# Vue.js / Vite
VITE_BASE_PATH: /projects/reports-demo/

# Nuxt
NUXT_APP_BASE_URL: /projects/reports-demo/

# NestJS / Go
BASE_PATH: /projects/reports-demo

# FastAPI
ROOT_PATH: /projects/reports-demo

Step 5: เพิ่ม depends_on ให้ reverse-proxy service

<NGINX_SERVICE>:
  depends_on:
    <APP_SERVICE>:
      condition: service_started

ถ้า service นั้น run จาก compose แยก ให้ไม่ต้องเพิ่ม depends_on แต่ต้องอยู่ network เดียวกัน.

Step 6: เพิ่ม PostgreSQL ถ้า backend ต้องใช้ DB

<DB_SERVICE>:
  image: postgres:16-alpine
  environment:
    POSTGRES_DB: <DB_NAME>
    POSTGRES_USER: <DB_USER>
    POSTGRES_PASSWORD: <DB_PASSWORD_ENV>
  volumes:
    - <DB_SERVICE>-data:/var/lib/postgresql/data
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U <DB_USER> -d <DB_NAME>"]
  expose:
    - "5432"
  networks:
    - <DOCKER_NETWORK>

reports-demo:
  environment:
    DATABASE_URL: postgresql://<DB_USER>:<DB_PASSWORD_ENV>@<DB_SERVICE>:5432/<DB_NAME>
  depends_on:
    <DB_SERVICE>:
      condition: service_healthy

backend ต้องใช้ host <DB_SERVICE> ไม่ใช่ localhost.

Step 7: เพิ่ม nginx route

location = /projects/reports-demo {
  set $reports_demo_upstream <APP_SERVICE>:3100;
  set $project_prefix /projects/reports-demo;
  proxy_pass http://$reports_demo_upstream;
}

location /projects/reports-demo/ {
  set $reports_demo_upstream <APP_SERVICE>:3100;
  set $project_prefix /projects/reports-demo;
  proxy_pass http://$reports_demo_upstream;
}

Step 8: เพิ่ม portal card

<a class="card" href="/projects/reports-demo/">
  <div class="card-header">
    <span class="card-badge">Demo</span>
    <span class="card-status">Ready</span>
  </div>
  <h3>Reports Demo</h3>
  <p>Short description of what this service demonstrates.</p>
  <code>/projects/reports-demo/</code>
</a>

Step 9: validate

docker compose -f services/docker-compose.yml config
docker exec <NGINX_CONTAINER> nginx -t
docker exec <NGINX_CONTAINER> nginx -s reload
curl -sL -o /dev/null -w '%{http_code} %{url_effective}\n' https://<PUBLIC_APP_HOST>/projects/reports-demo/
curl -sL -o /dev/null -w '%{http_code} %{url_effective}\n' https://<PUBLIC_APP_HOST>/projects/reports-demo/healthz

สำหรับรายละเอียดเต็ม ใช้ templates/docker-compose-portal-steps.md และ templates/postgres/README.md.

Templates Standard

templates/ คือ source of truth สำหรับเริ่ม service ใหม่. อย่า copy จาก app เก่าโดยตรงถ้า app นั้นมี history หรือ legacy config.

Quality Gates

Quality gate คือด่านผ่าน/ไม่ผ่านก่อน merge หรือ deploy. งาน production ต้องไม่จบแค่ container start ได้ แต่ต้องผ่าน dependency CVE, static analysis, image scan, build, nginx และ smoke route.

Standard Severity: MUST / SHOULD / MAY

Role-based Standards

Bad vs Good Examples (สำคัญมาก)

// Next.js fetch ที่หลุด base path
fetch('/api/healthz')

fetch(withBasePath('/api/healthz'))

proxy_pass http://app-service:3100/;

proxy_pass http://app-service:3100;

Definition of Done: New Service

• [ ] มี slug แบบ lowercase, path /projects/<slug>/.
• [ ] ใส่ base path และตรวจ route ด้วย curl.
• [ ] ควบคุม env ผ่าน .env/.compose ไม่ hardcode.
• [ ] มี /healthz, structured log, requestId.
• [ ] ไม่ commit secret, password, token, key.
• [ ] มี portal card และเชื่อมผ่าน nginx route ได้.
• [ ] ผ่าน quality gate และมี rollback note.

PR Review Checklist

• [ ] route และ base path ผ่าน checklist.
• [ ] architecture ไม่กระทบ service เดิม.
• [ ] API contract/response format ตรง standard.
• [ ] logging + audit ครอบ event สำคัญ.
• [ ] migration ใช้ up/down และมี rollback recovery.
• [ ] security ไม่มี secret จริงใน diff.
• [ ] run quality gate และผูก evidence ใน PR description.

Add New Service Checklist

1. เลือก slug เช่น reports-demo.
2. สร้าง app ใต้ services/projects/reports-demo หรือใช้ image ภายนอก.
3. ตั้ง container port เป็น 3100.
4. ตั้ง env base path เป็น /projects/reports-demo.
5. เพิ่ม service ใน compose หรือใช้ template ที่ตรง framework.
6. เพิ่ม nginx location ที่กำหนด $project_prefix และ upstream.
7. เพิ่ม portal card ที่ชี้ /projects/reports-demo/.
8. รัน compose config, nginx test, build, curl route และ asset check.