Codebase là gì? Toàn bộ code của dự án — 'kho tài liệu' bạn sở hữu khi thuê dev
Codebase là toàn bộ source code + cấu hình + dependencies của một phần mềm. Hiểu codebase giúp bạn đánh giá agency, đòi đúng quyền sở hữu, biết khi nào pivot sang stack mới và đo được 'sức khoẻ' dự án dev của mình.
Mục lục bài viết(12)
Cấu trúc codebase điển hình của một dự án Next.js: folder source code (app, components, lib, content), file cấu hình (package.json, next.config.ts), file secret (.env, không commit). node_modules/ KHÔNG tính là codebase vì sinh tự động qua npm install. Đây là codebase thực của vietcodex-app — 1 repository chứa cả landing site, wiki, admin và API.
Hiểu đơn giản nhất
Codebase = toàn bộ code (mã nguồn) tạo nên một phần mềm.
Tưởng tượng bạn mở một quán cà phê. Để vận hành quán, bạn cần một tủ tài liệu chứa:
- Menu món
- Công thức pha chế từng món
- Quy trình đón khách
- Danh sách nguyên liệu + nhà cung cấp
- Hợp đồng thuê mặt bằng + giấy phép
Tủ tài liệu này không phải là quán cà phê — quán phải có khách, có nguyên liệu, có nhân viên mới chạy được. Nhưng nếu thiếu tủ, bạn không thể mở quán mới ở chi nhánh khác, không thể onboard nhân viên mới, không thể đảm bảo chất lượng đồng đều.
Codebase chính là tủ tài liệu đó nhưng cho phần mềm. Phần mềm chạy được nhờ codebase + server + database + người dùng. Mất codebase = bạn không sửa được bug, không thêm tính năng mới, không deploy ở môi trường khác.
Tại sao bạn cần biết
- Đánh giá agency dev trước khi ký hợp đồng. Hỏi "Tôi có quyền sở hữu codebase sau khi thanh toán đủ không?" — câu trả lời "không" hoặc "ờm" là red flag.
- Đòi đúng tài sản khi hand-off. Khi dự án kết thúc, bạn cần codebase + tài liệu deploy + database schema — không phải link admin panel.
- Quyết định khi nào pivot stack. Codebase 50.000 dòng PHP 5.6 → cost migrate sang Node.js là bao nhiêu? Cần biết size mới ước được.
- Đo "sức khoẻ" dự án. Test coverage, build time, số bug/tháng — đều xuất phát từ codebase.
- Hiểu chi phí maintenance. Codebase to + cũ + ít test = chi phí maintenance cao. Codebase nhỏ + modern + nhiều test = nhanh thêm tính năng mới.
- Chuyển agency dễ hơn. Codebase có docs + convention rõ ràng → agency mới onboard 1 tuần. Codebase "tribal knowledge" (chỉ dev cũ hiểu) → mất 1-3 tháng + nhiều bug.
Codebase chứa những gì
Một codebase điển hình của dự án web 2026 có 6 nhóm file:
| Nhóm | Ví dụ file | Mục đích |
|---|---|---|
| Source code | .ts, .tsx, .css, .py, .go | Logic chính của ứng dụng |
| Cấu hình | package.json, tsconfig.json, next.config.ts | Khai báo dependencies + build settings |
| Content/asset | Ảnh, MDX, JSON data, font, video | Nội dung tĩnh người dùng thấy |
| Test | *.test.ts, *.spec.ts, e2e/ | Kiểm thử tự động |
| Tài liệu | README.md, docs/, CONTRIBUTING.md | Hướng dẫn cho dev |
| Script + tooling | scripts/, .github/workflows/, Dockerfile | Tự động hoá build, deploy, CI |
Có một số thứ KHÔNG được tính là codebase:
| Item | Tại sao KHÔNG | Ở đâu |
|---|---|---|
node_modules/ | Sinh tự động qua npm install từ package.json | Đọc từ npm registry |
| Database data | Code không chứa data — chỉ chứa schema (cấu trúc) | DB server |
.env (secrets) | Bí mật, không commit công khai | File riêng trên server |
dist/, .next/ (build output) | Sinh từ source code, có thể tạo lại | Local hoặc CI |
Log file .log | Sinh runtime, không phải code | Server hoặc log aggregator |
Cấu trúc codebase điển hình (Next.js)
Đây là cấu trúc của vietcodex-app (chính là codebase của trang bạn đang đọc):
vietcodex-app/
├── app/ # Routes + pages (Next.js App Router)
│ ├── (marketing)/ # Trang chủ, dịch vụ, bảng giá
│ ├── (wiki)/ # Wiki — chỗ này
│ ├── admin/ # Admin panel
│ └── api/ # API endpoints
├── components/ # React components dùng chung
│ ├── ui/ # Button, Input, Card, ...
│ ├── wiki/ # Sidebar, TOC, search modal
│ └── marketing/ # Hero, pricing card, ...
├── lib/ # Logic + helper
│ ├── auth.ts # Đăng nhập (better-auth)
│ ├── db.ts # Kết nối Postgres (Drizzle ORM)
│ ├── brand.ts # Thông tin brand (color, logo, slogan)
│ └── wiki/ # Helper riêng cho wiki (mdx parse, tree)
├── content/ # Content tĩnh (MDX)
│ └── wiki/
│ ├── co-ban/ # 23 bài Cluster 1
│ └── ai-coding/ # 11 bài Cluster 2
├── public/ # Asset tĩnh (ảnh, SVG, robots.txt)
├── scripts/ # Tool build (search index, ...)
├── drizzle/ # DB schema + migration
├── package.json # Dependencies + scripts
├── next.config.ts # Cấu hình Next.js
├── docker-compose.yml # Setup local dev
├── Dockerfile # Build image production
└── README.md # Hướng dẫn setup
Tổng số file: ~520 (không tính node_modules).
Tổng dòng code: ~28.000 (TypeScript + MDX + CSS).
Dependency count: 42 (production) + 18 (dev).
Build time: ~85 giây (Next.js build production).
Mỗi folder có mục đích riêng — đây là convention (quy ước chung) của hệ sinh thái Next.js. Dev mới vào project Next.js bất kỳ sẽ thấy cấu trúc tương tự → onboard nhanh.
Codebase nhỏ vs lớn — đo bằng số nào
| Quy mô | LOC (dòng code) | File | Dev team | Ví dụ |
|---|---|---|---|---|
| Tiny | < 1.000 | < 20 | 1 | Script automation, landing đơn giản |
| Small | 1.000-10.000 | 20-200 | 1-3 | Marketing site, MVP |
| Medium | 10.000-50.000 | 200-1.500 | 3-10 | SaaS giai đoạn early, e-commerce nhỏ |
| Large | 50.000-200.000 | 1.500-5.000 | 10-50 | SaaS đã có khách, mid-size product |
| Enterprise | 200.000-1.000.000 | 5.000-30.000 | 50-500 | Banking app, ERP, lớn corp |
| Hyperscale | > 1.000.000 | > 30.000 | > 500 | Google Search, Facebook, Stripe core |
So sánh ngữ cảnh thực tế:
- Linux Kernel (2026): ~30 triệu LOC, ~80.000 file. Codebase open-source lớn nhất.
- Chromium (Chrome browser): ~35 triệu LOC.
- Windows (rumour): ~50 triệu LOC.
- WordPress core (CMS): ~700.000 LOC.
- Next.js framework: ~250.000 LOC.
Codebase startup VN giai đoạn pre-Series A thường 20.000-80.000 LOC — không cần quá to để build được sản phẩm tốt.
Monorepo vs Polyrepo
Hai mô hình tổ chức codebase phổ biến:
| Yếu tố | Monorepo (1 repo nhiều project) | Polyrepo (mỗi project 1 repo) |
|---|---|---|
| Code chung (UI, types) | Dễ share — import trực tiếp | Phải publish package (npm) |
| Atomic commit (sửa nhiều project cùng PR) | Có | Không, phải 2-3 PR riêng |
| CI/CD complexity | Cao — cần biết file nào đổi để build subset | Thấp — mỗi repo CI riêng |
| Build time | Có thể chậm nếu không cache | Nhanh, mỗi repo độc lập |
| Onboard dev mới | Clone 1 repo là xong | Phải clone N repo |
| Tool support | Turborepo, Nx, pnpm workspace, Lerna | Native Git, không cần tool |
| Phù hợp | Team > 10 dev, share code chung nhiều | Team nhỏ, mỗi service độc lập |
| Ví dụ | Google (1 monorepo 2 tỷ LOC), Meta, vietcodex.com | Netflix (microservices polyrepo) |
Cảnh báo: Đừng dùng monorepo cho dự án nhỏ chỉ vì "trông pro". Polyrepo đơn giản hơn cho 90% startup VN.
Đánh giá health codebase — 8 chỉ số
Khi audit một codebase (của agency, của dự án bạn đang maintain, hoặc trước khi quyết định mua lại 1 startup), kiểm tra 8 thứ:
| Chỉ số | Tốt | Đáng lo | Cách đo |
|---|---|---|---|
| Test coverage | > 60% | < 20% | npm test -- --coverage |
| Build time | < 2 phút | > 10 phút | time npm run build |
| Dependencies outdated | < 10% | > 30% | npm outdated |
| Security vulnerabilities | 0 high/critical | > 5 high | npm audit |
| Linter errors | 0 | > 100 | npm run lint |
| TypeScript errors | 0 | > 50 | tsc --noEmit |
| README + docs | Có, < 3 tháng update | Không có hoặc cũ > 1 năm | Đọc bằng mắt |
| Last commit | < 1 tuần | > 6 tháng | Git log |
Một codebase 30.000 LOC nhưng đầy lỗi linter + dependency cũ 2 năm = cost maintenance gấp 3 lần codebase 60.000 LOC sạch sẽ + có test.
Ví dụ thực tế: codebase vietcodex-app
Codebase trang bạn đang đọc — số liệu cụ thể tháng 5/2026:
| Chỉ số | Giá trị |
|---|---|
| LOC (TypeScript + MDX) | ~28.000 |
| File | 520 |
| Dependencies (prod) | 42 |
| Dependencies (dev) | 18 |
| Build time | 85 giây |
| Bundle size (sau gzip) | ~340 KB |
| Test coverage | 32% (cần cải thiện) |
| TypeScript errors | 0 |
| Linter errors | 0 |
| Security vulnerabilities | 0 |
| Repo size (không node_modules) | 28 MB |
| Last commit | < 24 giờ |
Codebase này phục vụ 3 site cùng lúc qua 1 build:
vietcodex.com(marketing)wiki.vietcodex.com(chỗ bạn đang đọc)admin.vietcodex.com(CMS nội bộ)
Đây là monorepo nhẹ — KHÔNG dùng Turborepo, chỉ phân chia qua route group của Next.js App Router. Hợp lý vì 1 team, code chung nhiều (UI components, brand config, auth).
Cái gì có thể sai
| Vấn đề | Triệu chứng | Cách phòng |
|---|---|---|
| Tech debt tích tụ | Mỗi tính năng mới mất gấp đôi thời gian dự kiến | Dành 20% sprint cho refactor + viết test |
| Không ai sở hữu codebase | Bug rớt giữa team A và team B, không ai sửa | CODEOWNERS file (GitHub) + on-call rotation |
| Documentation cũ hơn code | Onboard dev mới mất 1 tháng, hỏi suốt | README + ADR (Architecture Decision Record) update theo PR |
| Dependencies cũ 2-3 năm | Security risk + không nâng cấp được framework | Renovate Bot tự tạo PR upgrade hàng tuần |
| Codebase "lock" bởi agency | Không deploy được nếu thiếu agency | Hợp đồng ghi rõ chuyển giao + deploy thử trước khi thanh toán cuối |
| Secret commit nhầm vào codebase | API key bị hacker dùng | .gitignore .env* + gitleaks pre-commit hook |
| Dead code (code không ai gọi) | Bundle to + dev confused | Tool knip, ts-prune scan định kỳ |
| Coupling cao giữa các module | Sửa A → B C D đều hỏng | Architecture review hàng quý + giảm dependency graph |
Codebase ownership — câu hỏi pháp lý quan trọng
Khi thuê agency làm web/app/SaaS, ai sở hữu codebase sau khi xong?
Mặc định theo Luật SHTT Việt Nam (Điều 27 Luật SHTT 2005, sửa 2022):
Tác giả của tác phẩm phái sinh (code do dev viết theo yêu cầu) có quyền tài sản đối với tác phẩm — TRỪ KHI hợp đồng quy định khác.
Dịch ra: agency mặc định giữ bản quyền nếu hợp đồng không nói gì. Bạn chỉ có quyền sử dụng (license), không có quyền chuyển nhượng / bán / sửa cho dùng đa mục đích.
Để bảo vệ mình, hợp đồng dịch vụ dev phải có 3 điều khoản:
- Chuyển giao toàn bộ quyền sở hữu trí tuệ (intellectual property — quyền sở hữu trí tuệ) đối với source code sau khi thanh toán đủ 100%.
- Bàn giao đầy đủ: source code (GitHub repo về account khách), tài liệu deploy, database schema, môi trường staging.
- Quyền tự deploy + tự thuê agency khác sửa mà không cần xin phép.
VietCodex luôn dùng pattern: push code lên GitHub account KHÁCH ngay từ commit đầu tiên — khách thấy progress realtime + sở hữu code 100% từ ngày 1 (không phải đợi xong dự án mới hand-off).
Tóm tắt 1 dòng
Codebase = toàn bộ code + config + content + test + docs của một dự án phần mềm. Lưu trong repository Git. KHÔNG bao gồm
node_modules(sinh tự động), data DB (riêng), secrets (.env). Khi thuê dev, ĐÒI sở hữu codebase rõ ràng trong hợp đồng — không có codebase thì không có quyền sửa/deploy/chuyển agency.
Đọc tiếp
- Git và GitHub là gì — codebase được lưu trữ + version control qua Git
- Framework là gì — quyết định framework = quyết định cấu trúc codebase
- Frontend vs Backend khác nhau ở đâu — 1 codebase có thể chứa cả 2, hoặc tách riêng
- HTML, CSS, JavaScript — 3 ngôn ngữ chiếm 90% codebase web 2026
- Web hoạt động thế nào — hành trình 200ms — codebase deploy lên server, user gọi qua HTTPS, dữ liệu trả về 200ms