Skip to content

AGENTS.md

Latest commit

 

History

History
136 lines (112 loc) · 6.55 KB

AGENTS.md

File metadata and controls

136 lines (112 loc) · 6.55 KB
Raw

AI agents instructions for Antares Web (AntaREST)

Antares Web is a web platform (REST API + React UI) by RTE for managing Antares Simulator studies. It is a monorepo with a Python/FastAPI backend in antarest/ and a React/TypeScript frontend in webapp/.

Tech stack

  • Backend: Python 3.11, FastAPI, Pydantic v2, SQLAlchemy 2 + Alembic, Celery/Redis, managed with uv (uv sync, uv run ...).
  • Frontend: Node 22.13, React 19, Vite, Redux Toolkit, TanStack Query/Router, MUI, vitest.
  • DB: SQLite for local/desktop, PostgreSQL for production.

Build, test, lint

Backend (run from repo root):

uv sync                                   # install deps (incl. dev)
uv run pytest -n auto                     # full test suite (parallel)
uv run pytest tests/study/test_x.py::test_name   # a single test
uv run ruff check antarest/ tests/ --fix  # lint + autofix
uv run ruff format antarest/ tests/       # format (line-length 120, double quotes)
uv run mypy                               # strict type check (config in pyproject.toml)

Frontend (run from webapp/):

npm install
npm run dev                               # Vite dev server (port 3000)
npm run test                              # vitest (runs with TZ=UTC)
npm run test -- src/path/File.test.tsx    # a single test file
npm run lint                              # tsc --noEmit + eslint
npm run build                             # tsc + vite build

Run the backend dev server: python antarest/main.py -c resources/application.yaml --auto-upgrade-db --no-front

Full checks (pytest + mypy + ruff) can be run via scripts/linter.sh. pre-commit hooks enforce mypy, ruff, and license headers.

Backend architecture

Entry points (see docs/architecture.md):

  • antarest/main.py — standalone dev server (single worker).
  • antarest/wsgi.py — gunicorn/uvicorn app for production.
  • antarest/gui.py — desktop application.
  • antarest/tools/admin.py — admin CLI.
  • worker services (antarest/worker/) — remote background jobs (e.g. unzip results).

Module layout: each feature package under antarest/ (e.g. study/, login/, launcher/, matrixstore/, core/) follows a consistent structure:

  • service.py — main service / facade.
  • web.py (or a web/ dir of blueprints) — FastAPI REST endpoints.
  • main.py — build_<service>() factory wiring dependencies.
  • model.py — business objects, DTOs, and DB entities (may be a directory).
  • repository.py — DB query helpers for the entities.
  • business/, dao/, adapters.py, utils.py — supporting logic.

The study/ package is the core domain (largest module): study storage lives in study/storage/ (raw studies, variant studies, upgraders), and DAOs in study/dao/.

Frontend architecture and conventions (webapp/)

Stack details: TanStack Router (file-based) + TanStack Query, Zod, Redux, react-hook-form, MUI (Emotion), i18next, Axios, Notistack, Vite, Vitest. Path alias @/* → src/*.

Never edit src/routeTree.gen.ts — generated by the TanStack Router plugin.

Source layout (webapp/src/):

  • routes/ — file-based routing: __root.tsx, _authenticated/ (auth layout guard), route.tsx = layout, index.tsx = index route, $param/ = dynamic segment. Dash-prefixed folders (-components/, -hooks/, -shared/) are colocated non-route code.
  • components/ — shared library: Form/, fieldEditors/, dialogs/, page/, Matrix/, etc.
  • services/api/ — axios wrappers per domain; shared client in services/api/client.ts (token injection + 401 logout via interceptors). Server responses are snake_case, so convert DTOs to camelCase models (helpers in services/utils/) using Zod.
  • queries/<domain>/ — TanStack Query: keys.ts (key factory), queries.ts, mutations.ts.
  • redux/ — global client state (ducks in redux/ducks/, selectors in redux/selectors.ts, typed hooks in redux/hooks/). Prefer TanStack Query for new server state; Redux is for app-wide client state (auth, UI).
  • hooks/, utils/, theme/, types/ — app-wide hooks, helpers, MUI theme, ambient types.

Conventions :

  • Style with the sx prop, not styled() (project practice). Use theme.vars.palette, never theme.palette directly; read the color mode via the useThemeColorScheme hook.
  • Imports: from @mui/material root (no subpaths); React types as React.ReactNode (not named type imports from react); import type for type-only imports; import i18n from "@/i18n", never from i18next.
  • No non-null assertions (!); no console.* (stripped in prod — surface errors to users via useEnqueueErrorSnackbar()).
  • i18n: keys in public/locales/{en,fr}/main.json, dot-namespaced (e.g. global.save); useTranslation() in components. Always add both en and fr translations.
  • Forms: use the <Form> component (components/Form/ submit error snackbars, and undo/redo. Build fields with the *FE editors in components/fieldEditors/ (RHF-aware via the reactHookFormSupport HOC); validators in utils/validation/.
  • Naming: PascalCase for component files/dirs.

Frontend tests: colocated in __tests__/ folders with jsdom and globals, setup in src/tests/setup.ts. Use test() not it(). Testing Library + user-event; no MSW — mock API modules with vi.mock.

Key conventions

  • License headers: every .py/.ts/.tsx file under antarest/, tests/, and webapp/ must start with the MPL-2.0 header (see top of antarest/main.py). It is checked in pre-commit and CI via scripts/license_checker_and_adder.py.
  • Typing: mypy runs in strict mode with explicit-override required; all backend code must be fully type-hinted.
  • Database changes: modify SQLAlchemy models (e.g. study/model.py), register new model files in antarest/dbmodel.py, then generate a migration with bash scripts/create_db_migration.sh "<message>" (needs ANTAREST_CONF set). Integration tests in tests/integration exercise the real Alembic migration path.
  • Commits & PR titles: Conventional Commits enforced by commitlint. Scope is required and must be lower/kebab-case, e.g. feat(study): ..., fix(ui): ....
  • Branching: git-flow. dev is the default branch; branch as feat/..., fix/..., docs/....

Tests

  • Backend tests are in tests/, mirroring the antarest/ package layout; shared fixtures are in tests/conftest*.py. testcontainers is used for Postgres-backed tests.
  • Frontend tests are colocated as *.test.ts(x) and run under vitest with TZ=UTC.