AGENTS.md

Guidance for AI coding agents working in the astron-rpa (AstronRPA) repository — an agent-ready RPA suite with out-of-the-box automation tools for desktop applications, web systems, and business-process automation.

AstronRPA uses a server–client architecture: server components run via Docker, and the client (RPA engine + desktop app) is packaged and run on the machine that executes RPA tasks. The client toolchain is Windows-first.

Project layout

This is a multi-language monorepo driven by a unified Makefile (with modular includes under makefiles/).

• backend/ — server-side microservices (deployed via Docker Compose):
  • robot-service/, resource-service/, rpa-auth/ — Java / Spring Boot services (Maven; each ships checkstyle.xml, pmd-ruleset.xml, spotbugs-exclude.xml).
  • ai-service/, openapi-service/ — Python services (managed with uv).
• engine/ — the Python RPA execution engine (managed with uv, linted with ruff): main.py, components/ (RPA components), servers/, shared/.
• frontend/ — pnpm workspace monorepo (Vue 3 + TypeScript, Vitest, ESLint, i18n under locales/). Notable packages under frontend/packages/: electron-app (desktop client), web-app (web console), browser-plugin, auth-app, cli, components, shared.
• docker/ — Docker Compose manifests for the server stack.
• makefiles/ — modular Make components (common.mk, python.mk, java.mk, typescript.mk, go.mk, git.mk).
• resources/ — packaged client resources. docs/, FAQ.md, BUILD_GUIDE.md — documentation.

Toolchain

• Python 3.13.x + uv 0.8+ — RPA engine and Python services.
• Node.js 22+ + pnpm 9+ — frontend workspace.
• Java JDK 8+ + Maven — Java backend services.
• Docker & Docker Compose — server deployment.
• Windows client packaging also needs SWIG (Python↔C/C++ bindings, e.g. pywinhook) and 7-Zip (deployment archives). See BUILD_GUIDE.md.

Common commands

Quality and git workflow are driven by the root Makefile (run make help to see detected projects and targets):

• make install-tools — install the formatting/linting toolchain.
• make fmt — format across languages (fmt-python, fmt-java, fmt-ts, …).
• make check (alias make lint) — format check + linters (check-python, check-java, check-ts, …). CI is check-only; it does not auto-fix.
• make new-feature name=<short-name> / make new-bugfix name=<short-name> — branch helpers following the project's branch strategy.

Pre-commit hooks (install with pre-commit install) format the engine with ruff: uv run --project engine --dev ruff format ./engine.

Run the server (Docker)

cd docker
cp .env.example .env
# configure the public HTTPS names and copy the certificate/key to docker/certs/
# see docker/HTTPS_DEPLOYMENT.md for required variables
docker compose up -d mysql casdoor
# wait for Casdoor initialization, then synchronize this deployment's credentials
python3 scripts/sync-casdoor-credentials.py
docker compose up -d
docker compose ps

Gateway API: https://localhost · Casdoor auth: https://localhost:8443

Build the client (Windows)

# full build (engine + frontend desktop app) from the repo root
./build.bat --python-exe "C:\Program Files\Python313\python.exe"
./build.bat --skip-frontend   # engine only
./build.bat --skip-engine     # frontend only

The packaged installer is written to frontend/packages/electron-app/dist/.

Frontend (pnpm workspace, from frontend/)

pnpm install
pnpm dev:web         # run the web console in dev
pnpm dev:desktop     # run the desktop app in dev
pnpm build:desktop   # build the Windows desktop app

Testing instructions

There is no aggregate make test; run tests per component:

• Frontend: pnpm test (Vitest) or pnpm test:run for a single run.
• Python (engine, backend/ai-service, backend/openapi-service): uv run pytest within the project where tests exist (e.g. backend/ai-service has a tests/ directory).
• Java (backend/robot-service, resource-service, rpa-auth): mvn test within the service directory.

Run make check and the relevant tests before opening a PR, and add or update tests for code you change.

Code style

Formatting and linting are wired through make fmt / make check:

PR instructions

• Create branches with the Make helpers (make new-feature name=<…>).
• Run make check and the relevant component tests before committing; make sure pre-commit hooks pass.
• Keep PRs focused and write clear, conventional commit messages.
• For build and deployment details, see BUILD_GUIDE.md.