Công nghệ
builderx_api là backend lõi cung cấp dữ liệu cho Storefront. Service được viết trên Phoenix Framework (Elixir) và phục vụ REST API, real-time channel, cũng như background worker cho toàn bộ sản phẩm — dữ liệu shop, đơn hàng, tài khoản, các tích hợp và search.
Kiến trúc
Cách builderx_api được phân lớp và tương tác với phần còn lại của hệ thống.
Cấu trúc dự án
builderxapi có hơn 120 module domain dưới lib/builderxapi/. Tài liệu này nhóm chúng theo trách nhiệm để dev mới định vị code nhanh.
Bounded context
Các bounded context (domain) trong lib/builderx_api/. Mỗi context sở hữu schema và hàm nghiệp vụ riêng. Quy tắc bất di bất dịch: chỉ chạm context từ bên ngoài, không gọi Repo trực tiếp.
Cài đặt
Quy trình khuyến nghị là dùng Docker để mọi người trong team đều dùng cùng phiên bản Elixir, Postgres và các service hỗ trợ. Cài Elixir native cũng được nếu bạn thích.
Cơ sở dữ liệu
builderx_api dùng nhiều hệ lưu trữ song song. Tài liệu này tập trung vào PostgreSQL + Citus (kho dữ liệu chính), kèm ghi chú nhanh cho Mongo / Redis / Elastic / QuestDB.
Tích hợp
Các dịch vụ ngoài và hạ tầng mà builderx_api phụ thuộc. Mỗi mục chỉ rõ vị trí code, cách bật/tắt và những điểm cần lưu khi phát triển.
Cronjob
builderx_api dùng Quantum (:quantum) làm scheduler. Tài liệu này mô tả vị trí code, quy ước và cách kiểm thử ở local.
Biến môi trường
builderxapi đọc cấu hình runtime ở config/envconfig.exs. Tệp mẫu cho local là .dev.env.
Triển khai
builderx_api được triển khai bằng Ansible với Elixir release đóng gói trong image Docker. Playbook nằm ở ansible/.
Extension & quy ước code
Quy ước code và bộ công cụ editor cho repo builderx_api.
Tài liệu tham khảo
Các tài liệu bên ngoài team thường tra cứu khi làm việc với builderx_api.
Lỗi thường gặp
Các vấn đề đã biết và cách xử lý nhanh cho builderx_api.
Runbook
Các thao tác vận hành thường gặp cho builderx_api. Mỗi block dưới đây mặc định chạy trong IEx shell bên trong container (make bash → iex -S mix), trừ khi có ghi chú khác.