987cc097da
- Added HeaderLayout component for the application header. - Introduced KeepAliveViewport for managing tab states and rendering. - Created TabNav for tab navigation with animated indicator. - Removed old Tabs component in favor of new layout structure. - Updated routing with AppRouter and defined appTabs for navigation. - Enhanced theme context to manage dark mode styles. - Added new UI components: Badge, Button, Separator, and Tabs. - Refactored pages to utilize new layout components and improve responsiveness. - Updated global styles for better theming and layout consistency. - Introduced TypeScript path aliases for cleaner imports.
64 lines
4.6 KiB
Markdown
64 lines
4.6 KiB
Markdown
# 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.
|