AIRegulation-DocAnalysis/AGENTS.md

AGENTS.md

Scope

• Backend code lives under backend/app/; frontend is the Vite app in frontend/.

Frontend UX Constraints

• Frontend work in frontend/ must target desktop Web first.
• Do not proactively add mobile-specific adaptations, responsive reflow for small screens, or mobile-first layout compromises unless the user explicitly asks for them.
• When desktop and mobile requirements conflict, preserve the desktop Web layout and interaction model by default.

Entrypoints

• Backend entrypoint is backend/app/main.py, which re-exports app from app.api.main.
• FastAPI mounts the real API under /api/v1; health endpoints are GET /health and GET /.
• Frontend API calls use relative /api URLs from frontend/src/api/index.ts.
• Current Vite dev proxy in frontend/vite.config.ts forwards /api to http://6.86.80.8:8000, not the local backend.

Preferred Commands

• Prefer the repo scripts over ad hoc startup commands: ./dev.sh ... on Unix, dev.bat ... on Windows.
• First-time local setup: ./dev.sh setup or dev.bat setup.
• Backend foreground dev server: ./dev.sh start api --foreground or dev.bat start api --foreground.
• Equivalent direct backend run from repo root: PYTHONPATH=backend uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload.
• Python tooling must use the repo-root .venv environment; do not use the global python.
• Prefer uv-managed execution from the repo root, for example uv run --python .venv\\Scripts\\python.exe python ... or other uv run ... forms that resolve within the project environment.
• Frontend dev: npm --prefix frontend run dev.
• Frontend verification: npm --prefix frontend run lint and npm --prefix frontend run build.
• Use npm, not pnpm; the checked-in scripts run npm install even though frontend/pnpm-lock.yaml also exists.

Env And Infra

• Backend settings must resolve env files from the repo root only. The supported files are root .env and optional root .env.development; files under backend/ must not be treated as authoritative env sources.
• The dev scripts read API_HOST, API_PORT, FRONTEND_PORT, and FRONTEND_MODE from root .env first, then root .env.development as an override; all other backend config comes from the repo-root env files via Pydantic settings.
• Docker infra is docker/docker-compose.yml; it brings up milvus, minio, redis, and postgres.
• Default ports from config/scripts: backend 8000, frontend 5173, Milvus 19530, MinIO 9000/9001, Redis 6379, PostgreSQL 5432.
• .env.example points embedding/LLM base URLs at a shared remote gateway http://6.86.80.4:30080/v1; do not assume model inference is local.

Verification

• Root pyproject.toml is the active Python manifest and pytest config; testpaths = ["tests"].
• Tests under tests/ insert backend/ into sys.path themselves, so targeted runs can be launched from the repo root.
• tests/test_milvus.py and tests/verify_mvp.py require Milvus and model/runtime dependencies; they are not cheap smoke tests.
• tests/verify_mvp.py also expects the BGEM3Embedder stack to be available and explicitly mentions FlagEmbedding.
• For backend-only changes, prefer focused import/startup checks unless you know the external services and model dependencies are available.

Backend Architecture Authority

• docs/architecture/backend-project-architecture.md is the authoritative backend architecture document for ongoing backend development.
• New backend business logic must follow api -> application -> domain ports -> infrastructure.
• Treat backend/app/shared/bootstrap.py as the current composition root for backend dependency wiring.
• Do not add new business orchestration to backend/app/services/* or backend/app/workflows/* unless the task is explicitly a migration step.
• API routes must not directly access ConversationStore; session access should go through application services.
• Legacy files may be patched for compatibility or bug fixes, but should not gain new long-term responsibilities.

Backend Commenting Standard

• All comments and docstrings in backend/**/*.py must be written in English.
• Every Python file under backend must include a module-level explanation and at least one meaningful # code comment.
• Every function and method must include a docstring.
• Files without functions, including __init__.py, schemas, enums, dataclasses, and export-only modules, must still include a module docstring, class docstrings when applicable, and at least one meaningful # code comment.
• Comments must explain intent, assumptions, invariants, or non-obvious logic; do not add empty, placeholder, or restatement-only comments.