Imported from duylw/aipower-jobsearch (AGENTS.md). Install upstream with npx skills add duylw/aipower-jobsearch. Copyright stays with the author.

AI Agent Core Rules & System Architecture Navigation (AGENTS.md)

Tài liệu này là kim chỉ nam (Single Source of Truth) quy định toàn bộ nguyên tắc kiến trúc, quy chuẩn viết code, quy trình làm việc và bản đồ điều hướng thư mục cho AI Assistant (Antigravity / Claude Code) trong suốt quá trình phát triển dự án AI-Powered High-Scale Job Aggregator & Search Platform.

1. Bản Đồ Điều Hướng Dự Án (Project & Directory Navigation)

Khi thực hiện bất kỳ tác vụ nào, AI Assistant PHẢI đọc và đối chiếu với cấu trúc chuẩn dưới đây:

agentic-system/
├── AGENTS.md                                # [BẠN ĐANG Ở ĐÂY] Quy tắc, kiến trúc & điều hướng
├── PROGRESS.md                              # Snapshot tiến độ & trạng thái dự án hiện tại
├── HOW_TO_USE_AI_PAIR_PROGRAMMER.md        # Cẩm nang quy trình tương tác với AI
├── PROJECT_IDEA_FULLSTACK_AI.md             # Đề bài, tầm nhìn dự án & mục tiêu CV
├── docs/
│   ├── ARCHITECTURE_AND_DECISIONS.md        # [QUAN TRỌNG] Nền tảng kiến trúc, lý do chọn stack & trade-offs
│   └── plans/                               # Kế hoạch triển khai chi tiết & Test plan từng module
│       ├── 01_infrastructure_docker.md
│       ├── 02_database_data_modeling.md
│       ├── 03_solr_search_engine.md
│       ├── 04_backend_mvc_api.md
│       ├── 05_caching_and_ingestion.md
│       ├── 05b_github_actions_ci.md
│       ├── 06_ai_hybrid_search_rrf.md
│       ├── 06b_ai_resume_matchmaker.md
│       ├── 07_frontend_web_ui.md
│       └── 08_testing_ci_benchmarks.md
├── backend/                                 # Toàn bộ mã nguồn Backend & Hạ tầng Multi-DB
│   ├── docker-compose.yml                   # Hạ tầng Multi-DB (Postgres, Solr, Mongo, Redis)
│   ├── .env.example                         # Biến môi trường mẫu
│   ├── .env                                 # Cấu hình môi trường (Git ignored)
│   ├── app/
│   │   ├── core/                            # Cấu hình (config.py, database.py, security.py, redis.py, solr.py)
│   │   ├── models/                          # Database ORM Models (SQLAlchemy & Mongo Schemas)
│   │   ├── schemas/                         # Pydantic Request/Response DTOs
│   │   ├── repositories/                    # Data Access Layer (SQL Queries, Mongo Operations, Solr Inverted Index)
│   │   ├── services/                        # Business Logic (Matching, Hybrid Search RRF, Caching Logic)
│   │   ├── controllers/                     # API Routers / Controllers (FastAPI Endpoints)
│   │   ├── workers/                         # Async Celery / Background Ingestion Pipeline
│   │   └── utils/                           # Helper functions, logger, custom exceptions
│   ├── tests/                               # Test Suite (Unit & Integration tests)
│   ├── scripts/                             # Scripts: infra healthcheck, 50k seeder, inspect_db
│   │   ├── infra/                           # check_services.py
│   │   ├── seeders/                         # seed_all.py, mock_data_generator.py
│   │   └── inspect_db.py                    # DB inspector CLI tool
│   ├── Dockerfile
│   ├── pyproject.toml                       # Quản lý dependencies & metadata qua uv
│   └── uv.lock                              # Lock file xác định môi trường đồng nhất
├── frontend/                                # Giao diện người dùng Web Responsive
│   ├── index.html                           # HTML5 Semantic structure
│   ├── styles/                              # Modern Vanilla CSS (Tokens, Glassmorphism, Layouts)
│   ├── scripts/                             # JS Controllers, Faceted Filter, AI Copilot Widget
│   └── assets/                              # Icons, static images
└── benchmarks/                              # Locust / k6 load testing scripts

2. Quy Tắc Kiến Trúc Bắt Buộc (Strict Architectural Rules)

2.1 Kiến Trúc Phân Lớp (Clean MVC / Layered OOP)

Bắt buộc tuân thủ luồng dữ liệu một chiều: $$\text{Controller (Router)} \longrightarrow \text{Service Layer} \longrightarrow \text{Repository Layer} \longrightarrow \text{Database / Solr / Redis}$$

1. Controller / Router (app/controllers/):
   • Chỉ chịu trách nhiệm: Nhận HTTP Request, validate dữ liệu đầu vào qua Pydantic Schema, gọi Service tương ứng, và trả về HTTP Response.
   • Tuyệt đối KHÔNG viết logic nghiệp vụ (business logic) hay truy vấn database/Solr trực tiếp tại Router.
2. Service Layer (app/services/):
   • Chứa toàn bộ business logic, tính toán điểm matching, thuật toán Hybrid Search (Reciprocal Rank Fusion - RRF), quy tắc Cache-Aside.
   • Giao tiếp với tầng dưới thông qua Repository. Không phụ thuộc trực tiếp vào HTTP Request/Response.
3. Repository Layer (app/repositories/):
   • Độc quyền xử lý giao tiếp CSDL (PostgreSQL SQLAlchemy Session, MongoDB PyMongo/Motor, Apache Solr pysolr/HTTP, Redis client).
   • Tách biệt hoàn toàn câu lệnh SQL/NoSQL khỏi business logic để dễ dàng Mocking khi viết Unit Test.
4. Model / Schema (app/models/, app/schemas/):
   • models/: SQLAlchemy ORM Entities mapping với bảng CSDL.
   • schemas/: Pydantic Models định nghĩa dữ liệu I/O (Request DTO, Response DTO, Validation Rules).

3. Quy Chuẩn Lập Trình & Coding Standards

3.1 Python (FastAPI Backend)

• Package Manager (uv): Bắt buộc sử dụng Astral uv làm công cụ quản lý package và môi trường ảo duy nhất:
  • Khởi tạo & quản lý dependencies qua pyproject.toml và uv.lock.
  • Cài đặt / thêm gói: uv add <package>, uv add --dev <package>.
  • Thực thi lệnh & scripts: Luôn chạy qua uv run (ví dụ: uv run pytest, uv run uvicorn app.main:app --reload).
  • Tối ưu Dockerfile với multi-stage build và cache mount của uv.
• Type Hints 100%: Tất cả function signature phải có đầy đủ type annotations cho arguments và return type (typing.List, typing.Optional, typing.Dict, v.v.).
• Pydantic v2: Sử dụng BaseModel, Field(), ConfigDict(from_attributes=True) để serialize/deserialize.
• Dependency Injection: Luôn sử dụng fastapi.Depends để inject Database Session, Redis Client, Solr Client và Repositories vào Controllers/Services.
• Xử lý Ngoại lệ (Centralized Error Handling):
  • Định nghĩa Custom Exceptions tại app/core/exceptions.py (EntityNotFoundError, SearchEngineError, InvalidFilterError).
  • Đăng ký Exception Handlers toàn cục tại app/main.py.
  • Không bao giờ để lộ raw database traceback cho client.
• Async/Await: Sử dụng async def cho các I/O-bound operations (FastAPI endpoints, Redis async, HTTP calls tới Solr/LLM).

3.2 Frontend (HTML5 / Vanilla CSS / Modern JS)

• Design Philosophy: Giao diện chuẩn mực, hiện đại (Vibrant Color Palette, Dark/Light Mode Tokens, Glassmorphism, Smooth Micro-animations).
• Không dùng Framework nặng nếu không cần thiết: Giữ mã nguồn gọn gàng, tải nhanh, tối ưu DOM manipulation với Vanilla JavaScript (ES6 Modules).
• Accessibility & SEO: Đầy đủ semantic tags (<header>, <main>, <aside>, <section>, <footer>), aria-* attributes, title tags và meta descriptions.

4. Quy Trình Làm Việc Chuẩn Với AI (Workflow Protocol)

Khi người dùng yêu cầu triển khai một tính năng hoặc module:

1. Kiểm tra trạng thái: Đọc PROGRESS.md để biết context hiện tại.
2. Mở tài liệu Plan tương ứng: Đọc file trong docs/plans/XX_module_name.md.
3. Thực hiện Atomic Step:
   • Bước 1: Tạo/sửa file theo kế hoạch (kèm đầy đủ type hints và docstrings).
   • Bước 2: Viết Unit Test / Integration Test tương ứng.
   • Bước 3: Chạy test kiểm chứng và báo cáo kết quả.
   • Bước 4: Cập nhật PROGRESS.md.

5. Quy Ước Cổng Kết Nối & Thông Số Cốt Lõi (System Constants)