# Global Project Constraints

1. **Language Requirements**: 
   - All code comments **MUST** be written in **English**.
   - All server and client logs (`console.log`, `logger.info`, `logger.error`, etc.) **MUST** be written in **English**.

2. **Internationalization (i18n)**:
   - All user-facing messages, API response messages, error messages, and UI text **MUST** guarantee internationalization support.
   - Do not use hardcoded string literals for messages. Always use the project's designated i18n service or translation utility with proper keys.

3. **UI Notifications**:
   - All popup messages, error alerts, and system notifications **MUST** uniformly use the toast component (e.g., via `useToast().showError()`, `showSuccess()`). 
   - Never use native browser `window.alert()`.

4. **Agent Architecture & Orchestration (v3.0)**:
   - High-complexity, multi-turn AI workflows (e.g., AI Tutor, Evaluation Agents) **MUST** use `LangGraph` for state machine orchestration. Do not rely on hardcoded linear `if-else` blocks or flat chains for multi-step agent interactions.
   - Separate distinct AI responsibilities (e.g., `QuestionGenerator`, `Grader`, `ReportAnalyzer`) into independent **Graph Nodes**.
   - Use **Conditional Edges (Routing)** to dynamically control the flow based on the graph state (e.g., triggering follow-up questions vs. proceeding to the next question).
   - The graph must maintain a central `State` object (e.g., `EvaluationState`) to track session data, current progress, multi-turn dialogue history, and interruption/recovery points (Thread IDs).

5. **Agent Evaluation & Anti-Hallucination**:
   - When using an LLM to grade or evaluate user input against a knowledge base, the Agent's System Prompt **MUST** always include the original reference documents (Ground Truth Chunks) to strictly prevent AI hallucination during scoring.

6. **Knowledge Graph Integration**:
   - When extracting complex relationships from documents for GraphRAG, ensure the LLM output conforms strictly to predefined schemas (Ontology) to prevent graph pollution.
   - Heavy extraction tasks (like Full Document Entity/Relation Extraction) must be handled asynchronously as background tasks, rather than blocking synchronous API calls.
