Documentation & AI Integration Manual

1. Platform Architecture Overview

V

Vercel Equivalent

S

Supabase / Neon

AI

Apple Metal AI

2. Zero-Leak Security Mandate

CRITICAL SECURITY MANDATE

Secrets from .env Only: ใช้ตัวแปร ${ELVAFLOW_PAT}, ${PROJECT_DB_PASSWORD} เสมอ
Protect .env File: ใส่ .env ใน .gitignore และแชร์เฉพาะ .env.example ที่มี Placeholders เท่านั้น
PAT Generation: ขอรับ PAT ได้จาก Console → Settings → Tokens (รูปแบบ elva_pat_...)
Tenant User Isolation (H-3): แอปพลิเคชันต้องเชื่อมต่อด้วยบทบาทเฉพาะ user_${PROJECT_SLUG} ห้ามใช้ superuser postgres

3. Complete Network & URLs Topology

บริบท (Context)	บริการ (Service)	URL / Hostname	พอร์ต / โปรโตคอล
Global Public Edge Cloudflare Tunnel	API & Web Console Production App Branch Preview	https://api.elvaflow.net https://console.elvaflow.net https://<slug>.elvaflow.net https://<slug>--<branch>.elvaflow.net	443 (HTTPS)
Local LAN Network Wi-Fi / VPN	S3 Storage Ingress MinIO Storage Console Forgejo Git Server	https://s3.elvaflow.home https://storage.elvaflow.home https://git.elvaflow.home	443 (HTTPS) SSH: 2222
Host Localhost Mac mini direct / SSH Tunnel	PostgreSQL 17 MinIO S3 API Ollama Metal AI Redis Cache	127.0.0.1:5432 http://127.0.0.1:9000 http://127.0.0.1:11434 127.0.0.1:6379	TCP 5432 HTTP 9000 HTTP 11434 TCP 6379
In-Container Docker backend-internal	PostgreSQL 17 MinIO S3 API Host Ollama AI	elvaflow-postgres:5432 http://elvaflow-minio:9000 http://host.docker.internal:11434	Internal DNS

4. PostgreSQL 17, pgvector & CoW Branching

Port 5432 Hardening (H-4): เชื่อมต่อจากภายนอกผ่าน SSH Tunnel

พอร์ต 5432 ถูกผูกไว้กับ 127.0.0.1 เท่านั้น หากพัฒนาบนโน้ตบุ๊กนอกเครื่อง Mac mini ให้สร้าง SSH Tunnel: ssh -L 5432:127.0.0.1:5432 user@<NODE_IP>

Database Connection Strings (.env format)

การสร้างตาราง Vector และ HNSW Index (768-d Embeddings)

-- สร้างตารางสำหรับเก็บ Document Embeddings
CREATE TABLE documents (
    id SERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    embedding vector(768)
);

-- สร้าง HNSW Index เพื่อเร่งความเร็วการค้นหาความหมาย
CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops);

-- ค้นหา 5 เอกสารที่มีความหมายใกล้เคียงที่สุด (Cosine Distance)
SELECT id, content, 1 - (embedding <=> '[...]'::vector) AS similarity
FROM documents ORDER BY similarity DESC LIMIT 5;

5. S3 Object Storage (MinIO)

6. Local AI Inference on Metal GPU

Call Chat Completion API (cURL)

7. Push-to-Deploy & GitOps Pipelines

.github/workflows/deploy.yml

8. Drop-in AI IDE Configurations

9. Agent 4-Step SOP

1 Verify Connectivity & Health

ตรวจสอบว่ามี ${ELVAFLOW_PAT} และทดสอบ curl -sI https://api.elvaflow.net/health

2 Isolated Database Branch

โคลนฐานข้อมูลชั่วคราวเพื่อพัฒนาฟีเจอร์: elvaflow db branch create feat-xyz (< 1s clone)

3 Develop & Run Migrations

รัน Prisma / Alembic Migration ใน DB Branch เพื่อทดสอบจนสมบูรณ์โดยไม่เสี่ยงกระทบ Production

4 Push-to-Deploy & Teardown

สั่ง Deploy ผ่าน GitHub Actions หรือ Webhook เพื่อรับ Live URL และลบ DB Branch ชั่วคราวคืนพื้นที่