Vietcodex
Public Engineering Standard v1.0 · áp dụng cho gói Custom

13 Engineering Principles

13 nguyên tắc kỹ thuật bắt buộc cho mọi dự án Vietcodex — không bao giờ vi phạm, không có ngoại lệ cho gói rẻ.

Đây là tài liệu public. Khi bạn thuê Vietcodex, bạn có thể audit chúng tôi theo 13 điểm này.

1

🔐Never commit secrets

Bí mật (API key, password, token, .env, JWT secret) không bao giờ được commit vào git repo.

Cụ thể

  • ▸.env, .env.local, .env.production — gitignored.
  • ▸.env.example chỉ chứa tên biến + ghi chú, không bao giờ chứa giá trị thật.
  • ▸Pre-commit hook scan secret pattern (TruffleHog hoặc gitleaks).
  • ▸Secret rotation ngay khi nghi lộ — không 'có lẽ ổn'.
⚠️ Hệ quả nếu vi phạm: Scrape bot rip secret trong 60 giây sau push public. Production có thể bị compromise.
2

🔒Password hashing — bcrypt ≥12 rounds (hoặc Argon2id)

Mật khẩu khách hàng không bao giờ lưu plain text. Hashing với bcrypt cost factor ≥12, hoặc Argon2id (preferred).

Cụ thể

  • ▸Better Auth handle mặc định đã đúng — không tự custom.
  • ▸Cost factor ≥12 → mỗi lần verify ~250ms, đủ chậm chống brute force.
  • ▸Reset password flow KHÔNG gửi password qua email — chỉ gửi token reset 1-lần.
3

🛡️Validate every input with Zod

Mọi user input ở API boundary phải qua Zod schema validation. Không có ngoại lệ.

Cụ thể

  • ▸Route handler đầu tiên là schema.parse(body) — fail ở đây, return 422.
  • ▸Type được suy ra từ schema (z.infer) — không khai báo type duplicate.
  • ▸Validation cho cả query string, body, params.
⚠️ Tại sao: Type-safety + runtime safety. Không bao giờ trust input từ client.
4

💉Parameterized queries only — never string concat

Database query qua Drizzle ORM hoặc sql tag parameterized. Không bao giờ string concatenation.

Cụ thể

  • ▸Drizzle query builder mặc định parameterized — dùng nó.
  • ▸Khi cần raw SQL: sql`...${userInput}...` (Drizzle template tag — auto-parameterize).
  • ▸KHÔNG dùng template literal native với userInput → SQL injection.
5

🚪Authorization check on every protected query

Mỗi query liên quan user data phải có authorization check — không tin tưởng URL/session blindly.

Cụ thể

  • ▸Self-hosted Postgres không có RLS mặc định → check trong service layer.
  • ▸Supabase Postgres → dùng RLS policies + service-layer check (defense in depth).
  • ▸Pattern: if (resource.ownerId !== user.id && user.role !== 'ADMIN') throw Forbidden.
  • ▸Audit log mọi access tới sensitive data.
⚠️ Tại sao: IDOR (Insecure Direct Object Reference) là lỗi top OWASP — quá dễ mắc nếu không thận trọng.
6

🚦Rate limit auth + payment + webhook endpoints

Mọi endpoint nhạy cảm phải có rate limit.

Cụ thể

  • ▸Login: 5 attempts / 15 phút / IP.
  • ▸Password reset request: 3 / giờ / email.
  • ▸Public form: 10 / phút / IP.
  • ▸Webhook: verify signature trước, rate limit sau.
  • ▸Dùng @upstash/ratelimit hoặc Cloudflare WAF rule.
7

🔐HTTPS only + HSTS + CSP

Production phải HTTPS-only. HSTS preload. Content-Security-Policy strict.

Cụ thể

  • ▸Vercel auto-redirect HTTP → HTTPS.
  • ▸HSTS header max-age=31536000; includeSubDomains; preload.
  • ▸CSP cấm inline script (trừ Next.js generated nonce).
  • ▸X-Frame-Options: DENY chống clickjacking.
  • ▸X-Content-Type-Options: nosniff.
8

🔷TypeScript strict mode — never `any`

tsconfig.json strict mode bật. any chỉ dùng có justification + comment giải thích.

Cụ thể

  • ▸strict: true, noImplicitAny, strictNullChecks, noUncheckedIndexedAccess.
  • ▸Thay any bằng unknown + type narrow.
  • ▸Generic + type inference > manual annotation.
  • ▸Run tsc --noEmit trong CI.
9

📝Conventional Commits

Mọi commit follow Conventional Commits format. Mọi PR title tương tự.

Cụ thể

  • ▸feat: add order export to Excel
  • ▸fix: prevent duplicate session creation
  • ▸refactor: extract payment validation into service
  • ▸test: add coverage for casso webhook auth
  • ▸docs: update DEPLOY.md with rollback instructions
⚠️ Tại sao: Auto-generated changelog. Easier sprint review. CI có thể block PR sai format.
10

🪝Pre-commit hook: lint + format + type check

Trước khi commit: ESLint pass, Prettier format, tsc --noEmit xanh.

Cụ thể

  • ▸.husky/pre-commit: pnpm exec lint-staged + pnpm exec tsc --noEmit.
  • ▸lint-staged auto-fix ESLint + Prettier trên file thay đổi.
⚠️ Hệ quả: CI ít fail vì lint/format issue. Code review focus vào logic.
11

👁️Pull Request requires Five-Axis Review pass

Mọi PR phải qua Five-Axis Code Review trước khi merge vào main.

Cụ thể

  • ▸1. Correctness — Functional + edge case + error path.
  • ▸2. Readability — Future dev onboard trong 1 ngày được không?
  • ▸3. Architecture — Pattern consistency, không tech debt mới.
  • ▸4. Security — OWASP, auth, validation, secret hygiene.
  • ▸5. Performance — N+1, pagination, async, bundle size.
12

🚀Production deploy requires green CI + audit + UAT

Không deploy production khi: CI fail, security audit fail, UAT chưa sign-off.

Cụ thể

  • ▸CI pass: ESLint 0 error, TypeScript clean, Vitest coverage ≥ 80%, Playwright E2E pass.
  • ▸pnpm audit: 0 high/critical CVE.
  • ▸Lighthouse: ≥ 90 Performance, ≥ 95 A11y/SEO/Best Practices.
  • ▸Audit: OWASP Top 10 manual review, RLS authorization audit, secret scan history.
  • ▸UAT: Customer sign-off biên bản nghiệm thu (PDF).
13

🔑Customer = Repo Owner from Day 1

Đây là principle quan trọng nhất — là gốc rễ của trust. Khách hàng là Owner của GitHub Org + Vercel + Supabase + Cloudflare từ Day 1, không phải Day 28.

Cụ thể

  • ▸Day 5: Tạo GitHub Org với khách là Owner. Team Vietcodex là Maintainer (remove Day 28).
  • ▸Code mỗi commit thuộc về khách ngay khi push.
  • ▸Khách có thể audit code, comment trên PR, dừng dự án bất cứ lúc nào — không sợ 'mất code'.
  • ▸Vercel/Supabase/Cloudflare account đều mời khách làm Owner ngay từ setup.
⚠️ Tại sao đảo ngược? Đa số agency truyền thống: dev team làm Owner → handover cuối dự án. Vấn đề: nếu agency biến mất, khách mất quyền truy cập. Vietcodex đảo ngược: khách Owner từ Day 1. Đây là structural trust — không phải lời hứa.

Audit Vietcodex theo 13 nguyên tắc

Bạn là khách hàng và muốn verify chúng tôi tuân thủ? Đề xuất 3 bước:

1

Trước khi ký hợp đồng

Yêu cầu xem 1-2 repo dự án trước (với consent khách cũ) để verify pattern thực tế.

2

Trong dự án

Request weekly audit report check 13 nguyên tắc — chúng tôi cung cấp miễn phí.

3

Cuối dự án

Biên bản nghiệm thu phải xác nhận 13 nguyên tắc compliance. Phát hiện vi phạm → refund hoặc fix miễn phí.

Sẵn sàng làm việc với agency có 13 nguyên tắc public?

Đặt lịch tư vấn 30 phút — chúng tôi sẽ map 13 nguyên tắc vào dự án của bạn.

Engineering Principles v1.0 — Phát hành 2026-05-15. Inspired by Class-AI-Agent production-grade workflow.